rhex 2.0.0 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8ddd109e085e6fd0019a06bcddeef878e5132045
-  data.tar.gz: 1693182acc5400722ae6598934f71d7dd85acf89
+  metadata.gz: 34f24c5201b8121902c9444446ba117b6ea44796
+  data.tar.gz: e66cdc381f1d92a64a5c55da8b89d1cc2c8c0602
 SHA512:
-  metadata.gz: 6db25e6a50b842d46d001f3c479c2e800f96dc0d96d66fd68e51297f6d2d8efdc52cc3c1f4abc34dc95ff1c10df3436be662b5e852a997d9c277ba18baf1411c
-  data.tar.gz: 0b40396657b73c09556af4923f6862a2df2b41bbce686c945ae9ab352780d4793c5b0a60a12a1401f457c72420947065b884ed52286bc2289fdf6d73ad2df25d
+  metadata.gz: e58d0a6d7c1bb83d1d4c13fe53059095d08f170e88db9b9da976d9fbbfb5e704b559334991ecdbf3f3d4e3df237df492f9f03d04083012d4d247b119e31e6497
+  data.tar.gz: 0a1fd3adf58cc2f0991977e127f00debf25697d4eb90a35106c1f5397e5486854a9794e6796602ff536de5dbf6260bb5e2fc2a8d914d4fae19a3232013e20936

data/lib/hex/axial_grid.rb

@@ -5,104 +5,131 @@ require_relative 'modules/grid_to_pic'
 # 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.
+#
+# @author Cédric ZUGER
+#
+# @attr_reader [Float] hex_ray the ray of an hexagon
+# @attr_reader [Float] hex_height the height of an hexagon
+# @attr_reader [Float] hex_width the width of an hexagon
+# @attr_reader [Float] quarter_height the quarter of the height of an hexagon
+# @attr_reader [Float] half_height the half of the height of an hexagon
+# @attr_reader [Float] half_width the half of the width of an hexagon
+#
 class AxialGrid
 
-  include GridToPic
-  include AsciiToGrid
+  attr_reader :hex_ray, :hex_height, :hex_width, :quarter_height, :half_width
 
-  # 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 color (see BaseHex::Axial.new) to a color. This is used to dump your grid to a bitmap field.
+  # Create an axial hexagon grid
   #
-  # Example
+  # @param hex_ray [Integer] the size of an hexagon. Please read : http://www.redblobgames.com/grids/hexagons/#basics for information about the size of an hexagon
   #
-  #   @g = Hex::Grid.new(
-  #    element_to_color_hash: {
-  #     m: :brown, g: :green, w: :blue
-  #    }
-  #   )
-  #
-  # Assuming you want all hex with a colorue 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
     @hex_ray = hex_ray
-    set_hex_dimensions
   end
 
-  # Set the hex colorue to color conversion hash
+  # Set the hex color to color conversion hash
+  #
+  # @param element_to_color_hash [Hash] see initialize
   #
-  # *Returns* : nothing.
   def set_element_to_color_hash( element_to_color_hash )
     @element_to_color_hash = element_to_color_hash
   end
 
   # Create an hexagon at a given position (q, r)
   #
-  # You can set a color for the hexagon and set the hex as a border hex or not
+  # @param q [Integer] the q coordinate of the hexagon
+  # @param r [Integer] the r coordinate of the hexagon
+  # @param color [String] a colorstring that can be used by ImageMagic
+  # @param border [Boolean] is the hex on the border of the screen (not fully draw)
+  # @param data [Unknown] some data associated with the hexagone. Everything you want, it is up to you.
+  #
+  # @return [AxialHex] an hexagon
   #
-  # *Returns* : an Hex::Axial object.
   def cset( q, r, color: nil, border: false, data: nil )
     @hexes[ [ q, r ] ] = AxialHex.new( q, r, color: color, border: border, data: data )
   end
 
-  # Same method, but accept an hexagon instead of (q, r) coords
+  # Insert an hexagon into the grid
+  #
+  # @param hex [AxialHex] the hexagon you want to add into the grid
+  #
+  # @return [AxialHex] the hexagon you inserted
   #
-  # *Returns* : the created Hex::Axial object.
   def hset( hex )
     @hexes[ [ hex.q, hex.r ] ] = hex
   end
 
   # Get the hexagon at a given position (q, r)
   #
-  # *Returns* : the created Hex::Axial object.
+  # @param q [Integer] the q coordinate of the hexagon
+  # @param r [Integer] the r coordinate of the hexagon
+  #
+  # @return [AxialHex] the hexagon at the requested position. nil if nothing
+  #
   def cget( q, r )
     @hexes[ [ q, r ] ]
   end
 
-  # Same method, but accept an hexagon instead of (q, r) coords
+  # Get the hexagon at a given position (q, r)
+  #
+  # @param hex [AxialHex] the hexagon containing the position you want to read
+  #
+  # @return [AxialHex] the hexagon at the requested position. nil if nothing
   #
-  # *Returns* : the created Hex::Axial object.
   def hget( hex )
     @hexes[ [ hex.q, hex.r ] ]
   end
 
   # Call the block for each Hex in the grid
   #
-  # *Returns* : nothing
+  # @example
+  #   mygrid.each{ |h| p h }
+  #
   def each
     @hexes.sort.each{ |h| yield h[1] }
   end
 
   # Return all surrounding hexes from grid
   #
-  # *Returns* : Array of AxialHex
+  # @param h [AxialHex] the hexagon you want to get surronding hexes
+  #
+  # @return [Array<AxialHex>] all surrounding hexes
   def h_surrounding_hexes( h )
     h.surrounding_hexes.map{ |sh| hget( sh ) }
   end
 
   # Get the hexagon at (x,y) coordinate.
   #
-  # *Returns* : the Hex::Axial object at x, y pos.
+  # @param x [Integer] the x coordinate of the hexagon you want to get
+  # @param y [Integer] the y coordinate of the hexagon you want to get
+  #
+  # @return [AxialGrid] the corresponding hex
+  #
   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 = AxialHex.new(q, r).round
     cget( hex.q, hex.r )
   end
+
+  #
+  # Get the (x, y) position of an hexagon object
+  #
+  # @param hex [AxialHex] the hexagon you want to get the position
   #
-  # Give the position of an hexagon object in pixel.
+  # @return [Array<Integer>] an array of two integers corrsponding respectively to the x, y values
   #
-  # *Returns* : an array of x, y positions.
   def to_xy( hex )
 
-    set_hex_dimensions
-
     tmp_q = hex.q
+    # x = ( @hex_ray * Math.sqrt(3) * ( tmp_q + hex.r/2.0 ) ) - @hex_width
+    # y = ( @hex_ray * 3.0/2.0 * hex.r ) - ( @quarter_height * 2 )
+
     x = ( @hex_ray * Math.sqrt(3) * ( tmp_q + hex.r/2.0 ) )
-    y = ( @hex_ray * 3.0/2.0 * hex.r )
+    y = ( @hex_ray * 3.0/2.0 * hex.r ) - ( @quarter_height * 2 )
+
     [ x, y ]
   end
 

data/lib/hex/axial_hex.rb

@@ -4,55 +4,66 @@ require_relative 'cube_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
+# Please read http://www.redblobgames.com/grids/hexagons/#coordinates to understand what an axial coordinates system is
+#
+# @attr_reader [Integer] q the q coordinate of the hexagon
+# @attr_reader [Integer] r the r coordinate of the hexagon
+#
 class AxialHex < BaseHex
 
-  attr_reader :q, :r #:nodoc:
+  attr_reader :q, :r
 
   # Directions around hex from top left clockwise
-  DIRECTIONS = [ [0,-1], [1,-1], [1,0], [0,1], [-1,+1], [-1,0] ] #:nodoc:
+  DIRECTIONS = [ [0,-1], [1,-1], [1,0], [0,1], [-1,+1], [-1,0] ]
 
   # Create an hexagon object
-  # - +q+ and +r+ are the coordinates in the axial coords system
-  # - +color+ : is a colorue 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.
+  # @param q [Integer] the q coordinate of the hexagon
+  # @param r [Integer] the r coordinate of the hexagon
+  # @param color [String] the color of the hexagon
+  # @param border [Boolean] true if the the hexagon is on the border
+  # @param data [Object] a data object associated with the hexagon. Anything you want
+  #
+  # @return [AxialHex] the AxialHex you created
+  #
   def initialize( q, r, color: nil, border: false, data: nil )
     @q = q
     @r = r
     super( color, border, data )
   end
 
-  # Check the equality between two hexagons.
-  def ==(h) #:nodoc:
+  # Test the equality between two hexagons
+  def ==(h)
     @q==h.q && @r==h.r
   end
 
-  def !=(h) #:nodoc:
+  # Test the inequality between two hexagons
+  def !=(h)
     @q!=h.q || @r!=h.r
   end
 
-  # Transform an axial represented hexagon object to a cube represented hexagon object.
+  # Transform an axial represented hexagon object to a cube represented hexagon object
+  #
+  # @return [CubeHex] a new CubeHex object
   #
-  # *Returns* : a new Hex::Cube object.
   def to_cube
     CubeHex.new(@q, -@q-@r, @r)
   end
 
   # From an array of hexagons, get the nearest
-  # - +hex_array+ : and array of Hex::Axial objects
   #
-  # Example
+  # @param hex_array [Array<AxialHex>] an array of AxialHex objects
+  #
+  # @example
+  #
+  #   hext_to_test = AxialHex.new( 5, 5 )
+  #   nearest_hex = AxialHex.new( 5, 6 )
+  #   far_hex = AxialHex.new( 20, 20 )
   #
-  #   hext_to_test = Hex::Axial.new( 5, 5 )
-  #   nearest_hex = Hex::Axial.new( 5, 6 )
-  #   far_hex = Hex::Axial.new( 20, 20 )
+  #   hext_to_test.nearset_hex( [ nearest_hex, far_hex ] )  #=> #<AxialHex @q=5, @r=6>
   #
-  #   nearest_hex.nearset_hex( [ hext_to_test, far_hex ] )  #=> #<Hex::Axial @q=5, @r=6>
+  # @return [AxialHex] the nearset hex as a AxialHex object
   #
-  # *Returns* : the nearset hex as a Hex::Axial object.
   def nearest_hex( hex_array )
     nearest_hex = nil
     current_distance = nil
@@ -71,28 +82,30 @@ class AxialHex < BaseHex
     nearest_hex
   end
 
-  ##
   # Compute the distance (in hex) between two hexagons
-  # - +h+ : an Hex::Axial object
   #
-  # Example
+  # @param h [AxialHex] a AxialHex object
   #
-  #   h1 = Hex::Axial.new( 5, 5 )
-  #   h2 = Hex::Axial.new( 20, 20 )
+  # @example
+  #
+  #   h1 = AxialHex.new( 5, 5 )
+  #   h2 = AxialHex.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
+  #   AxialHex.new( 5, 5 ).distance( AxialHex.new( 5, 5 ) )  #=> 0
+  #   AxialHex.new( 5, 5 ).distance( AxialHex.new( 5, 1 ) )  #=> 1
+  #
+  # @return [Integer] the distance between the two hexes (in hexes)
   #
-  # *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.
+  # @return [Array<AxialHex>] an array of AxialHex
+  #
   def surrounding_hexes
     # puts self.inspect, self.q.inspect, self.r.inspect
     DIRECTIONS.map{ |e| AxialHex.new( @q+e[0], @r+e[1] ) }
@@ -100,21 +113,24 @@ class AxialHex < BaseHex
 
   # 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
+  # @return [Boolean] 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)
   #
-  # *Returns* : an Hex::Axial with coords rounded.
+  # @return [AxialHex] an hex with coords rounded
+  #
   def round
     to_cube.round.to_axial
   end
 
   # Transform an hex to it's q, r coordinates
   #
-  # *Returns* : an array [ q, r ]
+  # @return [Array<Integer>] an array [ q, r ]
+  #
   def qr
     [ q, r ]
   end

data/lib/hex/base_hex.rb

@@ -1,9 +1,16 @@
+# This is the base hexagon class designed to be derived into axial and cube hexagons.
+# Sould never been instancied.
+#
+# @attr_reader [String] the color of the hexagon an ImageMagic compatible string
+# @attr_reader [Boolean] is the hexagon cut by the border of the picture
+# @attr_reader [Object] your data, anything you want
+#
 class BaseHex
-  attr_accessor :color, :border, :data #:nodoc:
+  attr_accessor :color, :border, :data
 
   def initialize( color = nil, border = nil, data = nil )
     @color = color if color
-    @border = @border if border
+    @border = border if border
     @data = data
   end
 end

data/lib/hex/cube_hex.rb

@@ -6,14 +6,21 @@ require_relative 'base_hex'
 # 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.
+#
+# @attr_reader [Integer] x the x coordinate of the cube representation of the hexagon
+# @attr_reader [Integer] y the y coordinate of the cube representation of the hexagon
+# @attr_reader [Integer] z the z coordinate of the cube representation of the hexagon
+#
 class CubeHex < BaseHex
 
-  attr_reader :x,:y,:z #:nodoc:
+  attr_reader :x,:y,:z
 
   # Create an hexagon object
-  # - +x+, +y+, +z+ are the coordinates in the axial coords system
   #
-  # *Returns* : a new Hex::Cube object.
+  # @param x [Integer] x coordinate
+  # @param y [Integer] y coordinate
+  # @param z [Integer] z coordinate
+  #
   def initialize( x, y, z, color: nil, border: nil, data: nil )
     @x = x
     @y = y
@@ -24,14 +31,16 @@ class CubeHex < BaseHex
 
   # Transform a cube represented hexagon to an Hexagon::Axial represented hexagon
   #
-  # *Returns* : a new Hex::Axial object.
+  # @return [AxialHex] a new AxialHex object
+  #
   def to_axial
     AxialHex.new(@x, @z, color: @color, border: @border, data: @data)
   end
 
-  # Round the float coordinates to integer coordinates.
+  # Round the float coordinates to integer coordinates
+  #
+  # @return [AxialCube] a new CubeHex object
   #
-  # *Returns* : a new Hex::Cube object.
   def round
     rx=@x.round(0)
     ry=@y.round(0)
@@ -53,7 +62,8 @@ class CubeHex < BaseHex
 
   # Compute the distance between two hexagons (in hexagons)
   #
-  # *Returns* : an integer : the distance between hex in hexagons.
+  # @return [Ingteger] 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/modules/ascii_to_grid.rb

@@ -1,8 +1,12 @@
 # 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
+  # Read an ascii file and load it into the hexagon grid.
+  #
+  # @param file_path [String] 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
+  #
+  # @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|
 
@@ -12,9 +16,11 @@ module AsciiToGrid
         elements = line.split
         q = 0
         elements.each do |element|
+          # puts "r = #{r} q = #{q}, test = #{( r == 0 || q == 0 )}"
           border = true if ( r == 0 || q == 0 )
-          shifted_q = q - ( r/2 )
-          cset( shifted_q, r, color: element, border: border )
+          # shifted_q = q - ( r/2 )
+          shifted_q = q
+          cset( shifted_q, r, color: element.to_sym, border: border )
           q += 1
         end
         r += 1
@@ -28,7 +34,6 @@ module AsciiToGrid
       end
 
       @hexes.each{ |key, e| e.border = true if e.r == ( max_r - 1 ) }
-
     end
   end
 

data/lib/hex/modules/grid_to_pic.rb

@@ -7,17 +7,15 @@ 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.
+# This module contain the methods to draw a grid to a picture file.
 module GridToPic
 
-  attr_reader :hex_height, :hex_width #:nodoc:
-  attr_reader :quarter_height, :half_width #:nodoc:
-
   # Draw the hex grid in a Magick::Image object
-  # - +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* : the Magick::Image object
+  # @param exit_on_error [Boolean] 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.
+  #
+  # @return [Magick::Image] a Magick::Image object
+  #
   def to_rmagick_image( 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'
@@ -45,10 +43,12 @@ module GridToPic
   end
 
   # Draw the hex grid on a Magick::Object and save it to a file
-  # - +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.
+  # @param exit_on_error [Boolean] 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
+  # @param pic_name [String] the name of the picture file (can be *.bmp, *.png, *.jpg)
+  #
+  # @return [Boolean] true if the file was created successfully, false otherwise
+  #
   def to_pic( pic_name, exit_on_error = true )
     canvas = to_rmagick_image( exit_on_error )
     canvas.write( pic_name )
@@ -58,6 +58,8 @@ module GridToPic
 
   def set_hex_dimensions
 
+    # p :call
+
     @hex_height = @hex_ray * 2.0
     @hex_width =  Math.sqrt(3)/2.0 * @hex_height
 
@@ -74,8 +76,8 @@ module GridToPic
   def draw_hex( gc, hex )
     x, y = to_xy( hex )
 
-    x -= @hex_width
-    y -= @quarter_height * 2
+    # p hex
+    # puts [ x, y ]
 
     color = get_color( hex )
     gc.fill( color.to_s )

data/lib/hex/square_grid.rb

@@ -1,12 +1,55 @@
 require_relative 'axial_grid'
 require_relative 'cube_hex'
 
+# This class represents a grid of hexagons stored in an axial coordinate system but manage the conversion to a square representation (what finally you want)
+#
+# @author Cédric ZUGER
+#
 class SquareGrid < AxialGrid
 
+  include AsciiToGrid
+  include GridToPic
+
+  # Create an axial hexagon grid
+  #
+  # @param hex_ray [Integer] the size of an hexagon.
+  # @param element_to_color_hash [Hash] a hash that relate color (see BaseHex::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 color of m are drawn in brown,g in green, etc ... (see GridToPic for drawing a grid)
+  #
+  def initialize( hex_ray: 16, element_to_color_hash: {} )
+    super( hex_ray: hex_ray )
+    @element_to_color_hash = element_to_color_hash
+    set_hex_dimensions
+  end
+
+  # Create an hexagon at a given position (col, row)
+  #
+  # @param col [Integer] the col coordinate of the hexagon
+  # @param row [Integer] the row coordinate of the hexagon
+  # @param color [String] a colorstring that can be used by ImageMagic
+  # @param border [Boolean] is the hex on the border of the screen (not fully draw)
+  # @param data [Unknown] some data associated with the hexagone. Everything you want, it is up to you
+  #
+  # @return [AxialHex] an hexagon
+  #
   def cset( col, row, color: nil, border: false, data: nil )
     hset( even_q_to_axial_hex( col, row, color: color, border: border, data: data ) )
   end
 
+  # Get the hexagon at a given position (col, row)
+  #
+  # @param col [Integer] the col coordinate of the hexagon
+  # @param row [Integer] the row coordinate of the hexagon
+  #
+  # @return [AxialHex] the hexagon at the requested position. nil if nothing
+  #
   def cget( col, row )
     hget( even_q_to_axial_hex( col, row ) )
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rhex
 version: !ruby/object:Gem::Version
-  version: 2.0.0
+  version: 2.0.1
 platform: ruby
 authors:
 - Cédric ZUGER