rhex 1.2.1 → 1.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6ba2d22ee5ac0982fc31d05f3a485b378f8503a2
-  data.tar.gz: 24917573a42bfff6c51db21390c212767c2b49be
+  metadata.gz: 4495c4b3d933607b7ea7e0b10bc42a122ff74c0c
+  data.tar.gz: ddd8919e2e5507048aba10dcd760f5bc89e862a0
 SHA512:
-  metadata.gz: b7da992847c675e39b7ecff68c0730994b679f8247b0c84662e9461a7ee7c498c0f5b8ef2d1d01c567f8f1ea6a313405a75e986ecff03296a235db71f2c0e3c0
-  data.tar.gz: 2e3b30f040101b88da3774cf6d543374e49c9dfc84133d311777f9820a090b795173152c7d38bfc7b980100f2859e59cbe07b4698d87fa33643fd51e374f7441
+  metadata.gz: de3022c9dc1cb096435ec471bc0adf61769abe5d2a4fae5f86d787e172f5b8e9ec70896543b38e4d31a559d2eea673d7b2189fa4be662ada04d4b1d102daddfe
+  data.tar.gz: c37e4bff873ef76137a4ee0d31164598af1c1ae2d50d53cc89e6f5c7f0828b31bd8ca305f234610615b0a7232324cecdb48d9f64bc12c1743fa9215aff324362

data/lib/hex/ascii_to_grid.rb

@@ -1,5 +1,8 @@
+# This module contains the methods relatives to ascii map reading
 module AsciiToGrid
 
+  #  Read an ascii file and load it into the hexagon grid.
+  #  - +file_path+ :  is the name of the ascii file to read. For how to create this file, please see : https://github.com/czuger/rhex#reading-a-grid-from-an-ascii-file
   def read_ascii_file( file_path )
     File.open( file_path ) do |file|
 

data/lib/hex/axial.rb

@@ -2,15 +2,26 @@
 
 require_relative 'cube'
 
+# This module contains is the container for all hexagon classes.
 module Hex
+
+  # This class represents an hexagon stored in axial coordinate system.
+  #
+  # Please read http://www.redblobgames.com/grids/hexagons/#coordinates
+  # to understand what an axial coordinates system is
   class Axial
 
-    attr_reader :q, :r, :val
+    attr_reader :q, :r, :val #:nodoc:
 
     # Directions around hex from top left clockwise
-    DIRECTIONS = [ [0,-1], [1,-1], [1,0], [0,1], [-1,+1], [-1,0] ]
-
-    # Create a new pointy topped axial represented hexagon object
+    DIRECTIONS = [ [0,-1], [1,-1], [1,0], [0,1], [-1,+1], [-1,0] ] #:nodoc:
+
+    # Create an hexagon object
+    # - +q+ and +r+ are the coordinates in the axial coords system
+    # - +val+ : is a value anything you want.
+    # - +border+ is a boolean and mean that the hex is at the border of the map.
+    #
+    # *Returns* : a new Hex::Axial object.
     def initialize( q, r, val: nil, border: false )
       @q = q
       @r = r
@@ -18,27 +29,44 @@ module Hex
       @border = border
     end
 
-    # Equality between two hexagons
-    def ==(h)
+    # Check the equality between two hexagons.
+    def ==(h) #:nodoc:
       @q==h.q && @r==h.r
     end
 
-    # Force the border status of the hex
+    # Force the border status of the hex.
+    #
+    # *Returns* : true.
     def border!
       @border = true
     end
 
-    # Get the border status of the hex
+    # Get the border status of the hex.
+    #
+    # *Returns* : true if the hex is at the border of the grid, false otherwise (only if border have been set. Return false otherwise).
     def border?
       !@border.nil?
     end
 
-    # Transform flat topped axial represented hexagon object to flat topped cube represented hexagon object
+    # Transform an axial represented hexagon object to a cube represented hexagon object.
+    #
+    # *Returns* : a new Hex::Cube object.
     def to_cube
       Hex::Cube.new(@q,-@q-@r,@r)
     end
 
-    # From an array of hexagones, get the nearest
+    # From an array of hexagons, get the nearest
+    # - +hex_array+ : and array of Hex::Axial objects
+    #
+    # Example
+    #
+    #   hext_to_test = Hex::Axial.new( 5, 5 )
+    #   nearest_hex = Hex::Axial.new( 5, 6 )
+    #   far_hex = Hex::Axial.new( 20, 20 )
+    #
+    #   nearest_hex.nearset_hex( [ hext_to_test, far_hex ] )  #=> #<Hex::Axial @q=5, @r=6>
+    #
+    # *Returns* : the nearset hex as a Hex::Axial object.
     def nearest_hex( hex_array )
       nearest_hex = nil
       current_distance = nil
@@ -53,26 +81,46 @@ module Hex
       nearest_hex
     end
 
-    # Get the distance (in hex) between two hexagons
+    ##
+    # Compute the distance (in hex) between two hexagons
+    # - +h+ : an Hex::Axial object
+    #
+    # Example
+    #
+    #   h1 = Hex::Axial.new( 5, 5 )
+    #   h2 = Hex::Axial.new( 20, 20 )
+    #
+    #   h1.distance( h2 )  #=> 30
+    #
+    #   Hex::Axial.new( 5, 5 ).distance( Hex::Axial.new( 5, 5 ) )  #=> 0
+    #   Hex::Axial.new( 5, 5 ).distance( Hex::Axial.new( 5, 1 ) )  #=> 1
+    #
+    # *Returns* : the distance between the two hexes as an integer.
     def distance( h )
       to_cube.distance(h.to_cube)
     end
 
     # Get all hexagons surrounding the current hexagon
+    #
+    # *Returns* : an array of Hex::Axial.
     def get_surrounding_hexs
       # puts self.inspect, self.q.inspect, self.r.inspect
       DIRECTIONS.map{ |e| Hex::Axial.new( @q+e[0], @r+e[1] ) }
     end
 
     # Check if an hexagon is around another hexagon
+    #
+    # *Returns* : true if the hexagon is adjacent to the other, false otherwise. Note, h.hex_surrounding_hex?( h ) == false
     def hex_surrounding_hex?(hex)
       distance(hex)==1
     end
 
     # Round an hexagon coordinates (useful after pixel to axial coordinate transformation)
-    # def round
-    #   to_cube.round.to_axial
-    # end
+    #
+    # *Returns* : an Hex::Axial with coords rounded.
+    def round
+      to_cube.round.to_axial
+    end
 
   end
 end

data/lib/hex/cube.rb

@@ -1,39 +1,57 @@
 module Hex
+
+  # This class represents an hexagon stored in a cube coordinate system.
+  #
+  # Please read http://www.redblobgames.com/grids/hexagons/#coordinates
+  # to understand what a cube coordinates system is
+  # The cube class is only for computation.
+  # It is not intended to be used directly in your program.
   class Cube
 
-    attr_reader :x,:y,:z
+    attr_reader :x,:y,:z #:nodoc:
 
+    # Create an hexagon object
+    # - +x+, +y+, +z+ are the coordinates in the axial coords system
+    #
+    # *Returns* : a new Hex::Cube object.
     def initialize(x,y,z)
       @x = x
       @y = y
       @z = z
     end
 
-    # Transform a cube represented hexagon to an Hexagon::Axial represented hexagon
+    # Transform a cube represented hexagon to an Hexagon::Axial represented hexagon
+    #
+    # *Returns* : a new Hex::Axial object.
     def to_axial
       Hex::Axial.new(@x,@z)
     end
 
-    # Round an float coordonate hexagon to an integer hexagon
-    # def round
-    #   rx=@x.round(0)
-    #   ry=@y.round(0)
-    #   rz=@z.round(0)
-    #
-    #   x_diff=(rx-@x).abs
-    #   y_diff=(ry-@y).abs
-    #   z_diff=(rz-@z).abs
+    # Round the float coordinates to integer coordinates.
     #
-    #   if x_diff > y_diff and x_diff > z_diff
-    #     rx = -ry-rz
-    #   elsif y_diff > z_diff
-    #     ry = -rx-rz
-    #   else
-    #     rz = -rx-ry
-    #   end
-    #   Hex::Cube.new(rx,ry,rz)
-    # end
+    # *Returns* : a new Hex::Cube object.
+    def round
+      rx=@x.round(0)
+      ry=@y.round(0)
+      rz=@z.round(0)
 
+      x_diff=(rx-@x).abs
+      y_diff=(ry-@y).abs
+      z_diff=(rz-@z).abs
+
+      if x_diff > y_diff and x_diff > z_diff
+        rx = -ry-rz
+      elsif y_diff > z_diff
+        ry = -rx-rz
+      else
+        rz = -rx-ry
+      end
+      Hex::Cube.new(rx,ry,rz)
+    end
+
+    # Compute the distance between two hexagons (in hexagons)
+    #
+    # *Returns* : an integer : the distance between hex in hexagons.
     def distance(h)
       [(@x - h.x).abs, (@y - h.y).abs, (@z - h.z).abs].max
     end

data/lib/hex/grid.rb

@@ -3,11 +3,30 @@ require_relative 'grid_to_pic'
 require_relative 'ascii_to_grid'
 
 module Hex
+
+  # This class represents a grid of hexagons stored in an axial coordinate system.
+  #
+  # Please read http://www.redblobgames.com/grids/hexagons/#coordinates to understand what an axial coordinates system is.
   class Grid
 
     include GridToPic
     include AsciiToGrid
 
+    # Create an hexagon object
+    # - +hex_ray+ is the size of an hexagon. Please read : http://www.redblobgames.com/grids/hexagons/#basics for information about the size of an hexagon.
+    # - +element_to_color_hash+ : is a hash that relate val (see Hex::Axial.new) to a color. This is used to dump your grid to a bitmap field.
+    #
+    # Example
+    #
+    #   @g = Hex::Grid.new(
+    #    element_to_color_hash: {
+    #     m: :brown, g: :green, w: :blue
+    #    }
+    #   )
+    #
+    # Assuming you want all hex with a value of m are drawn in brown,g in green, etc ... (see GridToPic for drawin a grid)
+    #
+    # *Returns* : a new Hex::Grid object.
     def initialize( hex_ray: 16, element_to_color_hash: {} )
       @hexes={}
       @element_to_color_hash = element_to_color_hash
@@ -16,39 +35,48 @@ module Hex
     end
 
     # Create an hexagon at a given position (q, r)
-    # You can set a value for the hexagon and set the hex as a border hex or not
+    #
+    # You can set a value for the hexagon and set the hex as a border hex or not
+    #
+    # *Returns* : an Hex::Axial object.
     def cset( q, r, val: nil, border: false )
       @hexes[ [ q, r ] ] = Hex::Axial.new( q, r, val: val, border: border )
     end
 
-    # Same method, but accept an hexagon instead of (q, r) coords
+    # Same method, but accept an hexagon instead of (q, r) coords
+    #
+    # *Returns* : the created Hex::Axial object.
     def hset( hex, val: nil, border: false )
       @hexes[ [ hex.q, hex.r ] ] = Hex::Axial.new( hex.q, hex.r, val: val, border: border )
     end
 
     # Get the hexagon at a given position (q, r)
+    #
+    # *Returns* : the created Hex::Axial object.
     def cget( q, r )
       @hexes[ [ q, r ] ]
     end
 
-    # Same method, but accept an hexagon instead of (q, r) coords
+    # Same method, but accept an hexagon instead of (q, r) coords
+    #
+    # *Returns* : the created Hex::Axial object.
     def hget( hex )
       @hexes[ [ hex.q, hex.r ] ]
     end
 
-    # Create an hexagon object from (x,y) coordinate
-    # q = (x * sqrt(3)/3 - y / 3) / size
-    # r = y * 2/3 / size
-    # return hex_round(Hex(q, r))
-    # def hex_at_xy(x, y)
-    #   # x-=@hex_width/2.0
-    #   # y-=@hex_height/2.0
-    #   q = (x * Math.sqrt(3)/3.0 - y/3.0) / @hex_ray
-    #   r = y * 2.0/3.0 / @hex_ray
-    #   Hex::Axial.new(q, r).round
-    # end
+    # Get the hexagon at (x,y) coordinate.
+    #
+    # *Returns* : the Hex::Axial object at x, y pos.
+    def hex_at_xy(x, y)
+      q = (x * Math.sqrt(3)/3.0 - y/3.0) / @hex_ray
+      r = y * 2.0/3.0 / @hex_ray
+      hex = Hex::Axial.new(q, r).round
+      hget( hex )
+    end
 
     # Give the position of an hexagon object in pixel.
+    #
+    # *Returns* : an array of x, y positions.
     def to_xy( hex )
       tmp_q = hex.q - ( hex.r/2.0 ).floor
       x = @hex_ray * Math.sqrt(3) * ( tmp_q + hex.r/2.0 )

data/lib/hex/grid_to_pic.rb

@@ -7,10 +7,17 @@ rescue Gem::LoadError
   puts 'Caution : Rmagick is not installed'
 end
 
+# This module contain methods to draw a grid to a picture file.
+# It is included in Grid.
 module GridToPic
 
-  attr_reader :hex_height, :hex_width
+  attr_reader :hex_height, :hex_width #:nodoc:
 
+  # Draw a picture of the hexagon grid
+  # - +pic_name+ : the name of the picture file (can be *.bmp, *.png, *.jpg)
+  # - +exit_on_error+ : by default, if you call this method and rmagic is not installed, the program exit with an error. You can disable it and make the program continue.
+  #
+  # *Returns* : true if the file was created successfully, false otherwise.
   def to_pic( pic_name, exit_on_error = true )
     unless defined?( Magick::Image ) && defined?( Magick::HatchFill ) && defined?( Magick::Draw )
       puts 'Rmagick is not installed !!! You can\'t dump hex grid to pic'
@@ -31,6 +38,8 @@ module GridToPic
     canvas.write( pic_name )
   end
 
+  private
+
   def set_hex_dimensions
 
     @hex_height = @hex_ray * 2.0
@@ -41,8 +50,6 @@ module GridToPic
 
   end
 
-  private
-
   def get_color( hex )
     color = @element_to_color_hash[ hex.val ]
     color ? color : :white

metadata

@@ -1,19 +1,19 @@
 --- !ruby/object:Gem::Specification
 name: rhex
 version: !ruby/object:Gem::Version
-  version: 1.2.1
+  version: 1.2.2
 platform: ruby
 authors:
 - Cédric ZUGER
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-12-28 00:00:00.000000000 Z
+date: 2015-12-31 00:00:00.000000000 Z
 dependencies: []
 description: |2
-      A library designed to provide hexagonal grids for ruby.
-      Provide various hex methods (surrounding hexes, nearest hex, distance between two hexes).
-      Provide also a method to create a grid from an ascii map and a method to dump your hex grid to a bitmap file (require rmagick).
+      A library providing hexagons management and hexagonal grids for ruby.
+      Misc methods (surrounding hexes, nearest hex, distance between hexes).
+      Can also create an hex grid from an ascii file and dump an hex grid to a picture.
 email: 
 executables: []
 extensions: []