hexagonly 0.1.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    YzNjMDVmZmQwZTZkNzQzODUzMjczNWNlZjBiYjkyYjZlOTRkZTUyMg==
+  data.tar.gz: !binary |-
+    NTYxM2RlOTQ2M2FiYTQ1N2QzYjBiNDdkZWI4MjY3MDY0ZWIxNWVkYQ==
+!binary "U0hBNTEy":
+  metadata.gz: !binary |-
+    MDY1NzlkNDgyZDhkZTFmYzkyMTE1M2UxODI5YzA0NjU0YmU4YTQ3MzA1YjNl
+    ZGE2MTYwMjk4NTE1ODdjNGE2NWEwZTM2ZGExYmJlOGFjODg2YzE0YjgwNTFk
+    MDNhYWU0NTJhMmVjZGRiMDc3ODI2MjZhMTBlZTk3ZmMzMDQyMjA=
+  data.tar.gz: !binary |-
+    YjM3MzAyMTVlNWNiODNiNzc0ZjUyZmUyZmQ5YmE5MTI0ODVlOWM2NGFmMDE0
+    NDZmMTYwNzdhNGRkYjQ3M2E1ZTY2YjlmNTgwNGIzZTU0M2ZkYTA0MTY0NTYw
+    OTI3YjhiYjIyYTcxNzUzZjRmYzAyNjMwODYzMzAxNDQ5NzEyMzk=

data/.gitignore

@@ -0,0 +1,24 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp
+
+# Ruby version
+.ruby-gemset
+.ruby-version
+
+# Roadmap
+roadmap.txt

data/.rspec

@@ -0,0 +1 @@
+--color

data/.ruby-gemset

@@ -0,0 +1 @@
+hexagonly

data/.ruby-version

@@ -0,0 +1 @@
+ruby-1.9.3-p448

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in hexagonly.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2013 lipanski
+
+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,265 @@
+# Hexagonly
+
+Provides helper classes for performing flat-topped hexagonal tiling and other polygon-related operations.
+
+## Motivation
+
+A personal project required me to **group geographical coordinates** on a map, compute different stats for individual groups 
+and display those stats in such a way that made them visually identify their groups.
+Squares and rectangles didn't really work for me, because different points on the boundries aren't equally distanced to the center.
+Circles would have been a good option for grouping objects in a 2-dimensional space, but then again
+circles are not really *tileable*.
+**Hexagons**, on the other hand, combine properties of the two shapes: they are easily tileable and have (sort of) a radius.
+
+I've tested this on my map project, but I guess it should work with **2D games** as well, or anything else that requires tiling or polygon-related operations.
+
+## Features
+
+- Currently supported shapes: Point, Polygon, Hexagon.
+- Define a **Polygon** and check whether a Point lies within its boundries (*crossing count* algorithm).
+- Define a **Hexagon** and determine its boundries, based on the hexagon center and size. All **Polygon** methods apply to this shape as well.
+- Generate **neighbouring Hexagons** for a given Hexagon.
+- **Hexagonal tiling**: generate hexagons to fill up a space, based on its boundries (two points suffice) and the hexagon size.
+- **Hexagonal tiling & collecting objects on the way**: generate hexagons to match the boundries of a given collection of Points (a *space*), then store contained Points (or custom objects) for every Hexagon.
+- Convert shapes (Polygon, Hexagon, Point) and mixed collections of shapes to **GeoJson**.
+- For every defined shape you can either use pre-defined classes or use your own custom classes, by including the appropriate **Hexagonly shape module**.
+
+The gem currently supports *flat-topped* hexagons only. For *pointy-topped* hexagons just place a bug request and I'll look into it.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'hexagonly'
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install hexagonly
+
+## Usage
+
+### Points
+
+There are 2 ways for defining Point objects:
+
+1. By using the pre-defined ``Hexagonly::Point`` class: 
+
+  ```ruby
+  point = Hexagonly::Point.new(1, 2)
+  
+  puts point.x_coord # => 1
+  puts point.y_coord # => 2
+  ```
+
+2. By using your custom class (e.g. think ActiveRecord) and including ``Hexagonly::Point::Methods`` 
+inside your class definition. Then you would assign your own accessors as coordinate getters and setters.
+This is accomplished via the class method ``x_y_coord_methods`` which takes two arguments: the names of the x and y coordinate accessors.
+The ``x_y_coord_methods`` defaults to ``:x`` and ``:y``.
+
+  ```ruby
+  class MyCustomPoint
+    include Hexagonly::Point::Methods
+    
+    # Sets accessors :a and :b as coordinate accessors
+    x_y_coord_methods :a, :b
+    
+    attr_accessor :a, :b
+    def initialize(a, b)
+      @a, @b = a, b
+    end
+  end
+  
+  point = MyCustomPoint.new(1, 2)
+  
+  puts point.x_coord # => 1
+  puts point.y_coord # => 2
+  ```
+
+### Poylgons
+
+The same 2 ways of instanciating apply to Polygons as well:
+
+1. By using the pre-defined ``Hexagonly::Polygon`` class:
+   
+   ```ruby
+   corners = [ Hexagonly::Point.new(2, 1), Hexagonly::Point.new(5, 5), Hexagonly::Point.new(6, 1), ... ]
+   poly = Hexagonly::Polygon(corners)
+
+   puts poly.poly_points # => corners...
+   puts poly.contains?(Hexagonly::Point(4, 2)) # => true
+   ```
+  
+2. By using custom classes, which include ``Hexagonly::Polygon::Methods`` and assigning custom corner accessor, set via the class method ``poly_points_method``.
+The ``poly_points_method`` method defaults to ``:poly_points``.
+  
+  ```ruby
+  class MyCustomPolygon
+    include Hexagonly::Polygon::Methods
+    
+    # Sets :corners as the polygon corners accessor
+    poly_points_method :corners
+    
+    attr_accessor :corners
+    def initialize(corners)
+      @corners = corners
+    end
+  end
+
+  corners = [ Hexagonly::Point.new(2, 1), Hexagonly::Point.new(5, 5), Hexagonly::Point.new(6, 1), ... ]
+  poly = MyCustomPolygon.new(corners)
+  
+  puts poly.poly_points # => corners...
+  puts poly.contains?(Hexagonly::Point(4, 2)) # => true
+  ```
+
+### Hexagons
+
+Hexagons inherit all methods of Polygons. There are 2 ways of creating new Hexagons:
+
+1. By using the pre-defined ``Hexagonly::Hexagon`` class:
+   
+  ```ruby
+  center = Hexagonly::Point.new(4, 4)
+  hexagon = Hexagonly::Hexagon.new(center, 1.5)
+
+  puts hexagon.hex_corners # => corners...
+  puts hexagon.contains?(center) # => true
+  ```
+
+2. By using a custom class, which includes ``Hexagonly::Hexagon::Methods``, and calling ``setup_hex`` on your instance:
+
+  ```ruby
+  class MyCustomHexagon
+    include Hexagonly::Hexagon::Methods
+    
+    def initialize(center, size)
+      setup_hex(center, size)
+    end
+  end
+
+  center = Hexagonly::Point.new(4, 4)
+  hexagon = MyCustomHexagon.new(center, 1.5)
+
+  puts hexagon.hex_center # => center
+  puts hexagon.hex_v_size # => distance from center to the top / bottom borders
+  puts hexagon.hex_corners # => corners...
+  puts hexagon.contains?(center) # => true
+  ```
+
+### Hexagonal tiling
+
+You start by defining your boundries. Boundries are basically a collection of 2 or more Hexagonaly::Point objects or objects including ``Hexagonly::Point::Methods``:
+
+```ruby
+boundries = [
+  Hexagonly::Point.new(1, 2),
+  Hexagonly::Point.new(4, 5),
+  ...
+]
+
+# Or you can use your custom Point class...
+boundries = [
+  MyCustomPoint.new(1, 2),
+  MyCustomPoint.new(4, 5),
+  ...
+]
+```
+
+Once you've defined your boundries, you can pass them to the ``Hexagonly::Hexagon.pack`` method. This takes 3 arguments:
+- the *boundries* or *points* that mark your hexagon field
+- half of the desired width of your hexagons (the distance from the center to the left / right boundries)
+- a *Hash* of additional parameters:
+  - ``:hexagon_class``: the class used to instanciate new Hexagons. Defaults to ``Hexagonly::Hexagon``. If you are
+  using custom Hexagon classes, you should include your class here.
+  - ``:point_class``: the class used to instanciate Hexagon center points. Defaults to ``Hexagonly::Point``.
+  - ``:grab_points``: a boolean, determining whether the first argument (points / boundries) will also be used to collect
+  contained points for every generated hexagon (see next category).
+  - ``:reject_empty``: a boolean, determining whether generated hexagons with no collected points should be removed from
+  the result. Only works if ``:grab_points`` is enabled (see next category).
+
+```ruby
+# Generated Hexagons will be Hexagonly::Hexagon instances
+hexagons = Hexagonly::Hexagon.pack(boundries, 0.3)
+
+# Generated Hexagons will be MyCustomHexagon instances
+hexagons = Hexagonly::Hexagon.pack(boundries, 0.3, { :hexagon_class => MyCustomHexagon })
+```
+
+### Hexagonal tiling & collecting objects on the way
+
+While generating your hexagons from a collection of Point objects, you might want to **store all contained points within individual hexagons**.
+This is accomplished by the same ``Hexagonly::Hexagon.pack`` method, only you'll need to enable the additional ``:grab_points`` parameter.
+Enabling the``:reject_empty`` parameter will remove all empty hexagons from the results Array.
+
+```ruby
+points = [
+  Hexagonly::Point.new(1, 1),
+  Hexagonly::Point.new(2, 2),
+  Hexagonly::Point.new(2, 3),
+  Hexagonly::Point.new(7, 1),
+  ...
+]
+
+hexagons = Hexagonly::Hexagon.pack(points, 0.25, { :grab_points => true, :reject_empty => true })
+
+puts hexagons[0].collected_points # => all objects from the points variable contained within this hexagon
+puts hexagons[0].collected_points[0].class # => Hexagonly::Point or your custom point class
+```
+
+### More examples
+
+While tiling and grabbing objects, you can also mix classes in your ``points`` collection, as long as they are
+compatible with ``Hexagonly::Point`` methods:
+
+```ruby
+class Salami
+  include Hexagonly::Point::Methods
+
+  # .x_y_coord_methods defaults to :x and :y
+  attr_accessor :x, :y
+  def initialize(x, y)
+    @x, @y = x, y
+  end
+end
+
+class Cheese
+  include Hexagonly::Point::Methods
+
+  attr_accessor :x, :y
+  def initialize(x, y)
+    @x, @y = x, y
+  end
+end
+
+class Pizza
+  include Hexagonly::Hexagon::Methods
+end
+
+# We have a couple of ingredients layed out on the table
+ingredients = [
+  Salami.new(1, 1),
+  Cheese.new(2, 2),
+  Cheese.new(3, 3),
+  Salami.new(4, 4),
+  ...
+]
+
+# And we want to create hexagonal pizzas out of them, by just laying the dough on top and removing the extra dough
+pizza_size = 1.0
+pizzas = Hexagonly::Hexagon.pack(ingredients, pizza_size, { :hexagon_class => Pizza, :grab_points => true, :reject_empty => true })
+
+puts pizzas[0].class # => Pizza
+puts pizzas[0].collected_points[0].class # => Salami or Cheese
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec
+task :test => :spec

data/hexagonly.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'hexagonly/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "hexagonly"
+  spec.version       = Hexagonly::VERSION
+  spec.authors       = ["Florin Lipan"]
+  spec.email         = ["lipanski@gmail.com"]
+  spec.description   = %q{Hexagonal tiling in Ruby.}
+  spec.summary       = %q{Provides helper classes for performing regular, flat-topped hexagonal tiling and other polygon-related operations.}
+  spec.homepage      = ""
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files`.split($/)
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  # General
+  spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "rake"
+  # Testing
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "factory_girl"
+  # Docs
+  spec.add_development_dependency "yard"
+  spec.add_development_dependency "redcarpet"
+
+end

data/lib/hexagonly/geo_json.rb

@@ -0,0 +1,34 @@
+require 'json'
+
+module Hexagonly
+  class GeoJson
+
+    attr_reader :features
+
+    # @param [Array] features an array of objects that support the #to_geojson method
+    def initialize(features = nil)
+      add_features(features) unless features.nil?
+    end
+
+    # Adds features (Points, Spaces, Hexagons) that support the #to_geojson method.
+    #
+    # @param [Array] features an array of objects that support the #to_geojson method
+    def add_features(features)
+      @features ||= []
+      features.each do |feat|
+        @features << feat.to_geojson
+      end
+    end
+
+    # Outputs the GeoJson string.
+    #
+    # @return [String] a valid GeoJSON string
+    def to_json
+      {
+        :type => "FeatureCollection",
+        :features => @features
+      }.to_json
+    end
+
+  end
+end

data/lib/hexagonly/hexagon.rb

@@ -0,0 +1,212 @@
+module Hexagonly
+  class Hexagon
+    
+    # Adds Hexagon methods to an object.
+    #
+    # @example
+    #   class MyHexagon
+    #     
+    #     include Hexagonly::Hexagon::Methods
+    #     
+    #     def initialize(center, size)
+    #       setup_hex(center, size)
+    #     end
+    #     
+    #   end
+    #
+    #   hex = MyHexagon.new(Hexagonly::Point.new(1, 2), 0.5)
+    #   hex.hex_corners # => an array containing all 6 corners of the hexagon
+    #   hex.contains?(Hexagonly::Point.new(1, 2)) # => true
+    #   hex.contains?(Hexagonly::Point.new(3, 3)) # => false
+    module Methods
+
+      include Hexagonly::Polygon::Methods
+      
+      def self.included(base)
+        base.extend(Hexagonly::Polygon::ClassMethods)
+        base.poly_points_method :hex_corners
+
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+
+        # Starting from the north-east corner of the given Points array and going east, 
+        # then repeating for every other row to the south, the method generates an 
+        # array of hexagons. If params[:grab_points] is true, every hexagon created 
+        # on the way grabs all the points contained within.
+        #
+        # @param points [Array<Hexagonly::Point>] the boundries for the generated hexagons
+        #   or an Array of points that will be "grabbed" by the generated hexagons 
+        #   (see @params[:grap_points])
+        # @param hex_size [Float] the size of the generated hexagons (width / 2)
+        # @param [Hash] params additional parameters
+        # @option params [false, true] :grab_points whether to "grab" points - 
+        #   stores included points unter hex#collected_points and excluded points
+        #   under hex#rejected_points
+        # @option params [false, true] :reject_empty when :grab_points is enabled
+        #   settings this option to true removes empty hexagons from the results
+        # @option params [Class] :hexagon_class the class used to instanciate new hexagons
+        # @option params [Class] :point_class the class used to instanciate hexagon center points
+        #
+        # @return [Array<Hexagonly::Hexagon] an array of hexagons
+        def pack(points, hex_size, params = {})
+          return [] if points.nil? || points.empty? || points.size < 2
+
+          hexagons = []
+          space = Hexagonly::Space.new(points)
+
+          h_hexagon_count = ((space.east.x_coord - space.west.x_coord) / (hex_size * 1.5)).abs.ceil
+          v_hexagon_count = ((space.north.y_coord - space.south.y_coord) / (hex_size * Math.cos(Math::PI / 6) * 2.0)).abs.ceil + 1
+
+          point_class = params.fetch(:point_class, Hexagonly::Point)
+          hexagon_class = params.fetch(:hexagon_class, Hexagonly::Hexagon)
+          grab_points = params.fetch(:grab_points, false)
+          reject_empty = params.fetch(:reject_empty, false)
+
+          north_west = point_class.new.tap{ |p| p.set_coords(space.west.x_coord, space.north.y_coord) }
+          hexagons << hex = hexagon_class.new.tap{ |h| h.setup_hex(north_west, hex_size); h.grab(points) if grab_points }
+          v_hexagon_count.times do |i|
+            first_hex = hex
+            h_hexagon_count.times do |j|
+              if j % 2 == 0
+                hexagons << hex = hex.north_east_hexagon(params)
+              else
+                hexagons << hex = hex.south_east_hexagon(params)
+              end
+            end
+
+            hexagons << hex = first_hex.south_hexagon(params) if i < v_hexagon_count - 1
+          end
+
+          if grab_points && reject_empty
+            hexagons.reject!{ |hex| hex.collected_points.empty? }
+          end
+
+          hexagons
+        end
+
+      end
+
+      attr_accessor :hex_center, :hex_size
+
+      # Initializes the hexagon.
+      #
+      # @param hex_center [Hexagonly::Point] the center of the hexagon
+      # @param hex_size [Float] the size of the hexagon (horizontal width / 2)
+      def setup_hex(hex_center, hex_size)
+        @hex_center, @hex_size = hex_center, hex_size
+      end
+
+      # The distance from the center of the hexagon to the top / bottom edges.
+      #
+      # @return [Float]
+      def hex_v_size
+        raise "hex_size not defined!" if @hex_size.nil?
+
+        @hex_size * Math.cos(Math::PI / 6)
+      end
+
+      # Checks whether the given point lies within the hexagon.
+      #
+      # @return [true|false]
+      def contains?(point)
+        loosely_contains?(point) ? super : false
+      end
+
+      # Checks whether the given point lies within the bounding box of the hexagon.
+      #
+      # @return [true|false]
+      def loosely_contains?(point)
+        raise "Call #setup_hex first!" if @hex_center.nil? || @hex_size.nil?
+
+        ((point.x_coord - @hex_center.x_coord).abs <= @hex_size) && ((point.y_coord - @hex_center.y_coord).abs <= hex_v_size)
+      end
+
+      # Returns a hexagon to the north-east with the same radius.
+      def north_east_hexagon(params = {})
+        raise "Call #setup_hex first!" if @hex_center.nil? || @hex_size.nil?
+
+        grab_points = params.fetch(:grab_points, false)
+
+        north_east_center = hex_point_class.new(@hex_center.x_coord + @hex_size * 1.5, @hex_center.y_coord + hex_v_size)
+        self.class.new.tap do |hex| 
+          hex.setup_hex(north_east_center, @hex_size)
+          hex.grab(@rejected_points) if grab_points
+        end
+      end
+
+      # Returns a hexagon to the south-east with the same radius.
+      def south_east_hexagon(params = {})
+        raise "Call #setup_hex first!" if @hex_center.nil? || @hex_size.nil?
+
+        grab_points = params.fetch(:grab_points, false)
+
+        south_east_center = hex_point_class.new(@hex_center.x_coord + @hex_size * 1.5, @hex_center.y_coord - hex_v_size)
+        self.class.new.tap do |hex| 
+          hex.setup_hex(south_east_center, @hex_size)
+          hex.grab(@rejected_points) if grab_points
+        end
+      end
+
+      # Returns a hexagon to the south with the same radius.
+      def south_hexagon(params = {})
+        raise "Call #setup_hex first!" if @hex_center.nil? || @hex_size.nil?
+
+        grab_points = params.fetch(:grab_points, false)
+
+        south_center = hex_point_class.new(@hex_center.x_coord, @hex_center.y_coord - hex_v_size * 2.0)
+        self.class.new.tap do |hex| 
+          hex.setup_hex(south_center, @hex_size)
+          hex.grab(@rejected_points) if grab_points
+        end
+      end
+
+      # Returns an array of the 6 points defining the corners of the hexagon.
+      #
+      # @return [Array<HexagonTiling::Point>] an array of points, coresponding to 
+      #   the 6 corners of the hexagon
+      def hex_corners
+        raise "Call #setup_hex first!" if @hex_center.nil? || @hex_size.nil?
+
+        corners = []
+        (0..5).each do |i|
+          angle = 2 * Math::PI / 6 * i
+          corner_x = @hex_center.x_coord + @hex_size * Math.cos(angle)
+          corner_y = @hex_center.y_coord + @hex_size * Math.sin(angle)
+          corners << hex_point_class.new(corner_x, corner_y)
+        end
+
+        corners
+      end
+
+      def to_geojson
+        corner_points = hex_corners.map{ |p| [p.x_coord, p.y_coord] }
+        corner_points << corner_points.last
+        {
+          :type => "Feature",
+          :geometry => {
+            :type => "Polygon",
+            :coordinates => [corner_points]
+          },
+          :properties => nil
+        }
+      end
+
+      private
+
+      def hex_point_class
+        @hex_center.nil? ? Hexagonly::Point : @hex_center.class
+      end
+
+    end
+
+    include Methods
+
+    # (see #setup_hex)
+    def initialize(*params)
+      setup_hex(*params) if params.size == 2
+    end
+
+  end
+end