pathfinding 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 10c0aa6e36e9928d826330a689ad3cf9767d35da2cdbd7549d166d39dd773cae
+  data.tar.gz: 0ffca62280a953128a6dce12fcf770327c047d0e34643a69bede0b6fadc8aa96
+SHA512:
+  metadata.gz: c2f8885e510048fb258f89001c9a00279180d39fd5b088464f45764660e6e25f4ba0646276d37a9e02551800c8742bef6fa44f279d698ad3a0f32c1e24f82c38
+  data.tar.gz: 953698ca4662703997497c94977ce312ed16ebe1a38e06955c4c794d36588a70d2e20ab1e345b04f874ba4508de95a38dd2139260021c3029afc273e0a3e8cab

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Quentin DESCHAMPS
+
+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,105 @@
+# Pathfinding in Ruby
+
+A pathfinding library in Ruby based on A* algorithm.
+
+Inpired by [python-pathfinding](https://github.com/brean/python-pathfinding)
+
+## Install
+To install the library, use the `gem` command:
+```
+gem install pathfinding
+```
+
+## Usage
+This is a simple example to find a path using A*.
+
+1. Import the library:
+```ruby
+require 'pathfinding'
+```
+2. Create a map using a 2D-list. Any value smaller or equal to 0 describes a walkable node. Any number bigger than 0 describes an obstacle. In this example, we added an obstacle in the middle.
+```ruby
+matrix = [
+  [0, 0, 0],
+  [0, 1, 0],
+  [0, 0, 0]
+]
+```
+Note: you can use negative values to describe different types of obstacles.
+
+3. Create a new grid from this map representation. This will create Nodes instances for every element of the map.
+```ruby
+grid = Grid.new(matrix)
+```
+
+4. Set the start and end point from the map. In this example, the start point is on top-left and the end point is on bottom-right.
+```ruby
+start_node = grid.node(0, 0)
+end_node = grid.node(2, 2)
+```
+
+5. Create a new instance of the finder and run the `find_path` method. If a path from start to the end point exists, this method returns the list of nodes of the path. Else, it returns an empty list.
+```ruby
+finder = AStarFinder.new()
+path = finder.find_path(start_node, end_node, grid)
+```
+Note:
+
+- You can choose the heuristic function to use using the `heuristic` argument.
+- You can also choose the diagonal movements allowed using the `diagonal_movement` argument.
+```ruby
+finder = AStarFinder.new(Heuristic::method(:manhattan), DiagonalMovement::NEVER)
+```
+See the [documentation](https://www.rubydoc.info/gems/pathfinding/0.0.1) for more details.
+
+6. Print the result (or do something else with it).
+```ruby
+puts grid.to_s(path, start_node, end_node)
+```
+The result should look like this:
+```
++---+
+|sxx|
+| #x|
+|  e|
++---+
+```
+* +, - and | characters show the border around the map
+* the blank space is a free field
+* 's' marks the start
+* 'e' marks the end
+* '#' is the obstacle
+* the 'x' characters mark the path from start to end
+
+This is the whole example:
+```ruby
+require 'pathfinding'
+
+matrix = [
+  [0, 0, 0],
+  [0, 1, 0],
+  [0, 0, 0]
+]
+grid = Grid.new(matrix)
+
+start_node = grid.node(0, 0)
+end_node = grid.node(2, 2)
+
+finder = AStarFinder.new()
+path = finder.find_path(start_node, end_node, grid)
+
+puts grid.to_s(path, start_node, end_node)
+```
+
+Take a look at the `examples/` folder for more examples.
+
+## Links
+- GitHub: https://github.com/Quentin18/pathfinding.rb
+- RubyGems: https://rubygems.org/gems/pathfinding
+- Documentation: https://www.rubydoc.info/gems/pathfinding/0.0.1
+
+## Author
+[Quentin Deschamps](mailto:quentindeschamps18@gmail.com)
+
+## License
+[MIT](https://choosealicense.com/licenses/mit/)

data/lib/pathfinding.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require 'pathfinding/core/diagonal_movement'
+require 'pathfinding/core/grid'
+require 'pathfinding/core/heuristic'
+require 'pathfinding/core/node'
+require 'pathfinding/finder/astar'

data/lib/pathfinding/core/diagonal_movement.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+#
+# File: diagonal_movement.rb
+# Author: Quentin Deschamps
+# Date: August 2020
+#
+
+#
+# Constants to set diagonal movements.
+#
+module DiagonalMovement
+  # Always accept diagonal movements.
+  ALWAYS = 1
+
+  # Never accept diagonal movements.
+  NEVER = 2
+
+  # Accept a diagonal movement if there is at most one obstacle.
+  IF_AT_MOST_ONE_OBSTACLE = 3
+
+  # Accept a diagonal movement only when there is no obstacle.
+  ONLY_WHEN_NO_OBSTACLE = 4
+end

data/lib/pathfinding/core/grid.rb

@@ -0,0 +1,187 @@
+# frozen_string_literal: true
+
+#
+# File: grid.rb
+# Author: Quentin Deschamps
+# Date: August 2020
+#
+
+require 'pathfinding/core/node'
+require 'pathfinding/core/diagonal_movement'
+
+#
+# Represents the grid as a 2d-list of nodes.
+#
+class Grid
+  include Enumerable
+
+  #
+  # Creates a grid from a matrix:
+  # * 0 (or less) represents a walkable node
+  # * A number greater than 0 does not represents a walkable node
+  # The +width+ represents the number of columns whereas the +height+
+  # is the number of rows of the grid. The +node+ attribute
+  # is the list of nodes.
+  #
+  def initialize(matrix)
+    @height = matrix.length
+    @width = matrix[0].length
+    @nodes = Grid.build_nodes(@width, @height, matrix)
+  end
+
+  #
+  # Gets the node at position (+x+, +y+).
+  #
+  def node(x, y)
+    @nodes[y][x]
+  end
+
+  #
+  # Yields all nodes of the grid.
+  #
+  def each_node
+    @height.times do |y|
+      @width.times do |x|
+        yield node(x, y)
+      end
+    end
+  end
+
+  #
+  # Creates a printable string from the grid using ASCII characters.
+  # Params:
+  # +path+:: list of nodes that show the path
+  # +start_node+:: start node
+  # +end_node+:: end node
+  # +border+:: create a border around the grid
+  # +start_chr+:: character for the start (default "s")
+  # +end_chr+:: character for the end (default "e")
+  # +path_chr+:: character for the path (default "x")
+  # +empty_chr+:: character for the empty fields (default " ")
+  # +block_chr+:: character for the blocking elements (default "#")
+  #
+  def to_s(
+    path = nil, start_node = nil, end_node = nil, border = true,
+    start_chr = 's', end_chr = 'e', path_chr = 'x', empty_chr = ' ', block_chr = '#'
+  )
+    data = []
+    data << '+' + '-' * @width + '+' if border
+    @height.times do |y|
+      line = ''
+      line += '|' if border
+      @width.times do |x|
+        current = node(x, y)
+        if current == start_node
+          line += start_chr
+        elsif current == end_node
+          line += end_chr
+        elsif path&.include?(current)
+          line += path_chr
+        elsif current.walkable
+          line += empty_chr
+        else
+          line += block_chr
+        end
+      end
+      line += '|' if border
+      data << line
+    end
+    data << '+' + '-' * @width + '+' if border
+    data.join("\n")
+  end
+
+  #
+  # Returns if the (+x+, +y+) position is in the grid.
+  #
+  def inside?(x, y)
+    x >= 0 && x < @width && y >= 0 && y < @height
+  end
+
+  #
+  # Returns if a node at position (+x+, +y+) is walkable.
+  #
+  def walkable?(x, y)
+    inside?(x, y) && node(x, y).walkable
+  end
+
+  #
+  # Get all neighbors of a node.
+  #
+  def neighbors(node, diagonal_movement=DiagonalMovement::NEVER)
+    x = node.x
+    y = node.y
+    neighbors = []
+    s0 = d0 = s1 = d1 = s2 = d2 = s3 = d3 = false
+
+    # ↑
+    if walkable?(x, y - 1)
+      neighbors << node(x, y - 1)
+      s0 = true
+    end
+
+    # →
+    if walkable?(x + 1, y)
+      neighbors << node(x + 1, y)
+      s1 = true
+    end
+
+    # ↓
+    if walkable?(x, y + 1)
+      neighbors << node(x, y + 1)
+      s2 = true
+    end
+
+    # ←
+    if walkable?(x - 1, y)
+      neighbors << node(x - 1, y)
+      s3 = true
+    end
+
+    return neighbors if diagonal_movement == DiagonalMovement::NEVER
+
+    if diagonal_movement == DiagonalMovement::ONLY_WHEN_NO_OBSTACLE
+      d0 = s3 && s0
+      d1 = s0 && s1
+      d2 = s1 && s2
+      d3 = s2 && s3
+    elsif diagonal_movement == DiagonalMovement::IF_AT_MOST_ONE_OBSTACLE
+      d0 = s3 || s0
+      d1 = s0 || s1
+      d2 = s1 || s2
+      d3 = s2 || s3
+    elsif diagonal_movement == DiagonalMovement::ALWAYS
+      d0 = d1 = d2 = d3 = true
+    else
+      raise 'Incorrect value of diagonal_movement'
+    end
+
+    # ↖
+    neighbors << node(x - 1, y - 1) if d0 && walkable?(x - 1, y - 1)
+
+    # ↗
+    neighbors << node(x + 1, y - 1) if d1 && walkable?(x + 1, y - 1)
+
+    # ↘
+    neighbors << node(x + 1, y + 1) if d2 && walkable?(x + 1, y + 1)
+
+    # ↙
+    neighbors << node(x - 1, y + 1) if d3 && walkable?(x - 1, y + 1)
+
+    neighbors
+  end
+
+  #
+  # Builds and returns the nodes.
+  #
+  def self.build_nodes(width, height, matrix)
+    nodes = []
+    height.times do |y|
+      nodes << []
+      width.times do |x|
+        walkable = matrix[y][x] <= 0
+        nodes[y] << Node.new(x, y, walkable)
+      end
+    end
+    nodes
+  end
+end

data/lib/pathfinding/core/heuristic.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+#
+# File: heuristic.rb
+# Author: Quentin Deschamps
+# Date: August 2020
+#
+
+#
+# A collection of heuristic functions.
+#
+module Heuristic
+  #
+  # Manhattan distance.
+  #
+  def self.manhattan(dx, dy)
+    dx + dy
+  end
+
+  #
+  # Euclidean distance.
+  #
+  def self.euclidean(dx, dy)
+    Math.sqrt(dx * dx + dy * dy)
+  end
+
+  #
+  # Octile distance.
+  #
+  def self.octile(dx, dy)
+    f = Math.sqrt(2) - 1
+    dx < dy ? f * dx + dy : f * dy + dx
+  end
+
+  #
+  # Chebyshev distance.
+  #
+  def self.chebyshev(dx, dy)
+    [dx, dy].max
+  end
+end

data/lib/pathfinding/core/node.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+#
+# File: node.rb
+# Author: Quentin Deschamps
+# Date: August 2020
+#
+
+#
+# Represents a node in the grid.
+#
+class Node
+  # Gets the x coordinate in the grid.
+  attr_reader :x
+
+  # Gets the y coordinate in the grid.
+  attr_reader :y
+
+  # Gets whether the node is walkable.
+  attr_reader :walkable
+
+  #
+  # Creates a node.
+  #
+  def initialize(x, y, walkable = true)
+    @x = x
+    @y = y
+    @walkable = walkable
+  end
+
+  #
+  # Makes the string format of a node.
+  #
+  def to_s
+    "(#{@x}, #{@y})"
+  end
+end

data/lib/pathfinding/finder/astar.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+#
+# File: astar.rb
+# Author: Quentin Deschamps
+# Date: August 2020
+#
+require 'pathfinding/core/grid'
+require 'pathfinding/core/diagonal_movement'
+require 'pathfinding/core/heuristic'
+
+#
+# A* path-finder.
+#
+class AStarFinder
+  #
+  # Initializes the A* path-finder. Params:
+  # * +heuristic+: heuristic function (see the +Heuristic+ module)
+  # * +diagonal_movement+: set diagonal movements (see the +DiagonalMovement+ module)
+  #
+  def initialize(
+    heuristic = Heuristic::method(:manhattan),
+    diagonal_movement = DiagonalMovement::NEVER
+  )
+    @diagonal_movement = diagonal_movement
+    if diagonal_movement == DiagonalMovement::NEVER
+      @heuristic = heuristic
+    else
+      @heuristic = Heuristic::method(:octile)
+    end
+  end
+
+  #
+  # Finds and returns the path as a list of node objects.
+  #
+  def find_path(start_node, end_node, grid)
+    open_set = [start_node]
+    came_from = {}
+    g_score = {}
+    f_score = {}
+    grid.each_node do |node|
+      g_score[node] = Float::INFINITY
+      f_score[node] = Float::INFINITY
+    end
+    g_score[start_node] = 0
+    f_score[start_node] = @heuristic.call(
+      (start_node.x - end_node.x).abs, (start_node.y - end_node.y).abs)
+
+    until open_set.empty?
+      current = open_set[0]
+      open_set.each do |node|
+        current = node if f_score[node] < f_score[current]
+      end
+
+      if current == end_node
+        return reconstruct_path(came_from, current)
+      end
+
+      current = open_set.delete_at(open_set.index(current))
+
+      grid.neighbors(current, @diagonal_movement).each do |neighbor|
+        tentative_g_score = g_score[current] + d(current, neighbor)
+        next if tentative_g_score >= g_score[neighbor]
+
+        came_from[neighbor] = current
+        g_score[neighbor] = tentative_g_score
+        f_score[neighbor] = g_score[neighbor] + @heuristic.call(
+          (neighbor.x - end_node.x).abs, (neighbor.y - end_node.y).abs)
+        unless open_set.include?(neighbor)
+          open_set << neighbor
+        end
+      end
+    end
+  end
+
+  #
+  # Returns the distance between two nodes.
+  #
+  def d(n1, n2)
+    (n1.x == n2.x || n1.y == n2.y) ? 1 : Math.sqrt(2)
+  end
+
+  #
+  # Reconstructs the path from the current node.
+  #
+  def reconstruct_path(came_from, current)
+    total_path = [current]
+    while came_from.include?(current)
+      current = came_from[current]
+      total_path << current
+    end
+    total_path.reverse
+  end
+end

data/pathfinding.gemspec

@@ -0,0 +1,32 @@
+Gem::Specification.new do |s|
+  s.name        = 'pathfinding'
+  s.version     = '0.0.1'
+  s.license     = 'MIT'
+  s.summary     = 'A pathfinding library based on A* algorithm.'
+  s.description = <<-DESCRIPTION
+    A pathfinding library based on A* algorithm.
+    Different options about heuristic and diagonal movements can be used.
+    The grid can be printed in the command prompt.
+  DESCRIPTION
+  s.author      = 'Quentin Deschamps'
+  s.email       = 'quentindeschamps18@gmail.com'
+  s.homepage    = 'https://github.com/Quentin18/pathfinding.rb'
+
+  s.require_paths = ['lib']
+  s.files = [
+    'lib/pathfinding.rb',
+    'lib/pathfinding/core/diagonal_movement.rb',
+    'lib/pathfinding/core/grid.rb',
+    'lib/pathfinding/core/heuristic.rb',
+    'lib/pathfinding/core/node.rb',
+    'lib/pathfinding/finder/astar.rb',
+    'LICENSE',
+    'README.md',
+    'pathfinding.gemspec'
+  ]
+
+  s.rdoc_options = ['--main', 'README.md']
+  s.extra_rdoc_files = ['LICENSE', 'README.md']
+
+  s.post_install_message = 'Thanks for installing!'
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: pathfinding
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Quentin Deschamps
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2020-08-18 00:00:00.000000000 Z
+dependencies: []
+description: |2
+      A pathfinding library based on A* algorithm.
+      Different options about heuristic and diagonal movements can be used.
+      The grid can be printed in the command prompt.
+email: quentindeschamps18@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- LICENSE
+- README.md
+files:
+- LICENSE
+- README.md
+- lib/pathfinding.rb
+- lib/pathfinding/core/diagonal_movement.rb
+- lib/pathfinding/core/grid.rb
+- lib/pathfinding/core/heuristic.rb
+- lib/pathfinding/core/node.rb
+- lib/pathfinding/finder/astar.rb
+- pathfinding.gemspec
+homepage: https://github.com/Quentin18/pathfinding.rb
+licenses:
+- MIT
+metadata: {}
+post_install_message: Thanks for installing!
+rdoc_options:
+- "--main"
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key:
+specification_version: 4
+summary: A pathfinding library based on A* algorithm.
+test_files: []