theseus 1.0.0

data/lib/theseus/orthogonal_maze.rb

@@ -0,0 +1,195 @@
+require 'theseus/maze'
+
+module Theseus
+  # An orthogonal maze is one in which the field is tesselated into squares. This is
+  # probably the type of maze that most people think of, when they think of mazes.
+  #
+  # The orthogonal maze implementation in Theseus is the most complete, supporting
+  # weaving as well as all four symmetry types. You can even convert any "perfect"
+  # (no loops) orthogonal maze to a "unicursal" maze. (Unicursal means "one course",
+  # and refers to a maze that has no junctions, only a single path that takes you
+  # through every cell in the maze exactly once.)
+  #
+  #   maze = Theseus::OrthogonalMaze.generate(width: 10)
+  #   puts maze
+  class OrthogonalMaze < Maze
+    def potential_exits_at(x, y) #:nodoc:
+      [N, S, E, W]
+    end
+
+    # Extends Maze#finish! to make sure symmetrical mazes are properly closed.
+    #--
+    # Eventually, this would be good to generalize somehow, and make available to
+    # the other maze types.
+    #++
+    def finish! #:nodoc:
+      # for symmetrical mazes, if the size of the maze in the direction of reflection is
+      # even, then we have two distinct halves that need to be joined in order for the
+      # maze to be fully connected.
+
+      available_width, available_height = @width, @height
+
+      case @symmetry
+      when :x then
+        available_width = available_width / 2
+      when :y then
+        available_height = available_height / 2
+      when :xy, :radial then 
+        available_width = available_width / 2
+        available_height = available_height / 2
+      end
+
+      connector = lambda do |x, y, ix, iy, dir|
+        start_x, start_y = x, y
+        while @cells[y][x] == 0
+          y = (y + iy) % available_height
+          x = (x + ix) % available_width
+          break if start_x == x || start_y == y
+        end
+
+        if @cells[y][x] == 0
+          warn "maze cannot be fully connected"
+          nil
+        else
+          @cells[y][x] |= dir
+          nx, ny = move(x, y, dir)
+          @cells[ny][nx] |= opposite(dir)
+          [x,y]
+        end
+      end
+
+      even = lambda { |x| x % 2 == 0 }
+
+      case @symmetry
+        when :x then
+          connector[available_width-1, rand(available_height), 0, 1, E] if even[@width]
+        when :y then
+          connector[rand(available_width), available_height-1, 1, 0, S] if even[@height]
+        when :xy then
+          if even[@width]
+            x, y = connector[available_width-1, rand(available_height), 0, 1, E]
+            @cells[@height-y-1][x] |= E
+            @cells[@height-y-1][x+1] |= W
+          end
+
+          if even[@height]
+            x, y = connector[rand(available_width), available_height-1, 1, 0, S]
+            @cells[y][@width-x-1] |= S
+            @cells[y+1][@width-x-1] |= N
+          end
+        when :radial then
+          if even[@width]
+            @cells[available_height-1][available_width-1] |= E | S
+            @cells[available_height-1][available_width] |= W | S
+            @cells[available_height][available_width-1] |= E | N
+            @cells[available_height][available_width] |= W | N
+          end
+      end
+
+      super
+    end
+
+    # Takes the current orthogonal maze and converts it into a unicursal maze. A unicursal
+    # maze is one with only a single path, and no dead-ends or junctions. Such mazes are
+    # more properly called "labyrinths". Note that although this method will always return
+    # a new OrthogonalMaze instance, it is not guaranteed to be a valid maze unless the
+    # current maze is "perfect" (not braided, containing no loops).
+    #
+    # The resulting unicursal maze will be twice as wide and twice as high as the original
+    # maze.
+    #
+    # The +options+ hash can be used to specify the <code>:entrance</code> and
+    # <code>:exit</code> points for the resulting maze. Currently, both the entrance and
+    # the exit must be adjacent.
+    #
+    # The process of converting an orthogonal maze to a unicursal maze is straightforward;
+    # take the maze, and divide all passages in half down the middle, making two passages.
+    # Dead-ends become a u-turn, etc. This is why the maze increases in size.
+    def to_unicursal(options={})
+      unicursal = OrthogonalMaze.new(options.merge(width: @width*2, height: @height*2, prebuilt: true))
+
+      set = lambda do |x, y, direction, *recip|
+        nx, ny = move(x, y, direction)
+        unicursal[x,y] |= direction
+        unicursal[nx, ny] |= opposite(direction) if recip[0]
+      end
+
+      @cells.each_with_index do |row, y|
+        row.each_with_index do |cell, x|
+          x2 = x * 2
+          y2 = y * 2
+
+          if cell & N != 0
+            set[x2, y2, N]
+            set[x2+1, y2, N]
+            set[x2, y2+1, N, true] if cell & W == 0
+            set[x2+1, y2+1, N, true] if cell & E == 0
+            set[x2, y2+1, E, true] if (cell & PRIMARY) == N
+          end
+
+          if cell & S != 0
+            set[x2, y2+1, S]
+            set[x2+1, y2+1, S]
+            set[x2, y2, S, true] if cell & W == 0
+            set[x2+1, y2, S, true] if cell & E == 0
+            set[x2, y2, E, true] if (cell & PRIMARY) == S
+          end
+
+          if cell & W != 0
+            set[x2, y2, W]
+            set[x2, y2+1, W]
+            set[x2+1, y2, W, true] if cell & N == 0
+            set[x2+1, y2+1, W, true] if cell & S == 0
+            set[x2+1, y2, S, true] if (cell & PRIMARY) == W
+          end
+
+          if cell & E != 0
+            set[x2+1, y2, E]
+            set[x2+1, y2+1, E]
+            set[x2, y2, E, true] if cell & N == 0
+            set[x2, y2+1, E, true] if cell & S == 0
+            set[x2, y2, S, true] if (cell & PRIMARY) == E
+          end
+
+          if cell & (N << UNDER_SHIFT) != 0
+            unicursal[x2, y2] |= (N | S) << UNDER_SHIFT
+            unicursal[x2+1, y2] |= (N | S) << UNDER_SHIFT
+            unicursal[x2, y2+1] |= (N | S) << UNDER_SHIFT
+            unicursal[x2+1, y2+1] |= (N | S) << UNDER_SHIFT
+          elsif cell & (W << UNDER_SHIFT) != 0
+            unicursal[x2, y2] |= (E | W) << UNDER_SHIFT
+            unicursal[x2+1, y2] |= (E | W) << UNDER_SHIFT
+            unicursal[x2, y2+1] |= (E | W) << UNDER_SHIFT
+            unicursal[x2+1, y2+1] |= (E | W) << UNDER_SHIFT
+          end
+        end
+      end
+
+      enter_at = unicursal.adjacent_point(unicursal.entrance)
+      exit_at = unicursal.adjacent_point(unicursal.exit)
+
+      if enter_at && exit_at
+        unicursal.add_opening_from(unicursal.entrance)
+        unicursal.add_opening_from(unicursal.exit)
+
+        if enter_at[0] < exit_at[0]
+          unicursal[enter_at[0], enter_at[1]] &= ~E
+          unicursal[enter_at[0]+1, enter_at[1]] &= ~W
+        elsif enter_at[1] < exit_at[1]
+          unicursal[enter_at[0], enter_at[1]] &= ~S
+          unicursal[enter_at[0], enter_at[1]+1] &= ~N
+        end
+      end
+
+      return unicursal
+    end
+
+    private
+
+    def configure_symmetry #:nodoc:
+      if @symmetry == :radial && @width != @height
+        raise ArgumentError, "radial symmetrial is only possible for mazes where width == height"
+      end
+    end
+  end
+end

data/lib/theseus/path.rb

@@ -0,0 +1,91 @@
+module Theseus
+  # The Path class is used to represent paths (and, generally, regions) within
+  # a maze. Arbitrary metadata can be associated with these paths, as well.
+  #
+  # Although a Path can be instantiated directly, it is generally more convenient
+  # (and less error-prone) to instantiate them via Maze#new_path.
+  class Path
+    # Represents the exit paths from each cell in the Path. This is a Hash of bitfields,
+    # and should be treated as read-only.
+    attr_reader :paths
+
+    # Represents the cells within the Path. This is a Hash of bitfields, with bit 1
+    # meaning the primary plane for the cell is set for this Path, and bit 2 meaning
+    # the under plane for the cell is set.
+    attr_reader :cells
+
+    # Instantiates a new plane for the given +maze+ instance, and with the given +meta+
+    # data. Initially, the path is empty.
+    def initialize(maze, meta={})
+      @maze = maze
+      @paths = Hash.new(0)
+      @cells = Hash.new(0)
+      @meta = meta
+    end
+
+    # Returns the metadata for the given +key+.
+    def [](key)
+      @meta[key]
+    end
+
+    # Marks the given +point+ as occupied in this path. If +how+ is +:over+, the
+    # point is set in the primary plane. Otherwise, it is set in the under plane.
+    #
+    # The +how+ parameter is usually used in conjunction with the return value of
+    # the #link method:
+    #
+    #   how = path.link(from, to)
+    #   path.set(to, how)
+    def set(point, how=:over)
+      @cells[point] |= (how == :over ? 1 : 2)
+    end
+
+    # Creates a link between the two given points. The points must be adjacent.
+    # If the corresponding passage in the maze moves into the under plane as it
+    # enters +to+, this method returns +:under+. Otherwise, it returns +:over+.
+    #
+    # If the two points are not adjacent, no link is created.
+    def link(from, to)
+      if (direction = @maze.relative_direction(from, to))
+        opposite = @maze.opposite(direction)
+
+        if @maze.valid?(from[0], from[1])
+          direction <<= Maze::UNDER_SHIFT if @maze[from[0], from[1]] & direction == 0
+          @paths[from] |= direction
+        end
+
+        opposite <<= Maze::UNDER_SHIFT if @maze[to[0], to[1]] & opposite == 0
+        @paths[to] |= opposite
+
+        return (opposite & Maze::UNDER == 0) ? :over : :under
+      end
+
+      return :over
+    end
+
+    # Adds all path and cell information from the parameter (which must be a
+    # Path instance) to the current Path object. The metadata from the parameter
+    # is not copied.
+    def add_path(path)
+      path.paths.each do |pt, value|
+        @paths[pt] |= value
+      end
+
+      path.cells.each do |pt, value|
+        @cells[pt] |= value
+      end
+    end
+    
+    # Returns true if the given point is occuped in the path, for the given plane.
+    # If +how+ is +:over+, the primary plane is queried. Otherwise, the under
+    # plane is queried.
+    def set?(point, how=:over)
+      @cells[point] & (how == :over ? 1 : 2) != 0
+    end
+
+    # Returns true if there is a path from the given point, in the given direction.
+    def path?(point, direction)
+      @paths[point] & direction != 0
+    end
+  end
+end

data/lib/theseus/sigma_maze.rb

@@ -0,0 +1,107 @@
+require 'theseus/maze'
+
+module Theseus
+  # A "sigma" maze is one in which the field is tesselated into hexagons.
+  # Trying to map such a field onto a two-dimensional grid is a little tricky;
+  # Theseus does so by treating a single row as the hexagon in the first
+  # column, then the hexagon below and to the right, then the next hexagon
+  # above and to the right (on a line with the first hexagon), and so forth.
+  # For example, the following grid consists of two rows of 8 cells each:
+  #
+  #    _   _   _   _
+  #   / \_/ \_/ \_/ \_
+  #   \_/ \_/ \_/ \_/ \ 
+  #   / \_/ \_/ \_/ \_/ 
+  #   \_/ \_/ \_/ \_/ \ 
+  #     \_/ \_/ \_/ \_/ 
+  #
+  # SigmaMaze supports weaving, but not symmetry (yet).
+  #
+  #   maze = Theseus::SigmaMaze.generate(width: 10)
+  #   puts maze
+  class SigmaMaze < Maze
+
+    # Because of how the cells are positioned relative to other cells in
+    # the same row, the definition of the diagonal walls changes depending
+    # on whether a cell is "shifted" (e.g. moved down a half-row) or not.
+    #
+    #    ____        ____
+    #   / N  \      /
+    #  /NW  NE\____/
+    #  \W    E/ N  \
+    #   \_S__/W    E\____
+    #        \SW  SE/
+    #         \_S__/
+    #
+    # Thus, if a cell is shifted, W/E are in the upper diagonals, otherwise
+    # they are in the lower diagonals. It is important that W/E always point
+    # to cells in the same row, so that the #dx and #dy methods do not need
+    # to be overridden.
+    #
+    # This change actually makes it fairly easy to generalize the other
+    # operations, although weaving needs special attention (see #weave_allowed?
+    # and #perform_weave).
+    def potential_exits_at(x, y) #:nodoc:
+      [N, S, E, W] + 
+        ((x % 2 == 0) ? [NW, NE] : [SW, SE])
+    end
+
+    private
+
+    # This maps which axis the directions share, depending on whether a cell
+    # is shifted (+true+) or not (+false+). For example, in a non-shifted cell,
+    # E is on a line with NW, so AXIS_MAP[false][E] returns NW (and vice versa).
+    # This is used in the weaving algorithms to determine which direction an
+    # UNDER passage moves as it passes under a cell.
+    AXIS_MAP = {
+      false => {
+        N => S,
+        S => N,
+        E => NW,
+        NW => E,
+        W => NE,
+        NE => W
+      },
+
+      true => {
+        N => S,
+        S => N,
+        W => SE,
+        SE => W,
+        E => SW,
+        SW => E
+      }
+    }
+
+    # given a path entering in +entrance_direction+, returns the side of the
+    # cell that it would exit if it passed in a straight line through the cell.
+    def exit_wound(entrance_direction, shifted) #:nodoc:
+      # if moving W into the cell, then entrance_direction == W. To determine
+      # the axis within the new cell, we reverse it to find the wall within the
+      # cell that was penetrated (opposite(W) == E), and then
+      # look it up in the AXIS_MAP (E<->NW or E<->SW, depending on the cell position)
+      entrance_wall = opposite(entrance_direction)
+      AXIS_MAP[shifted][entrance_wall]
+    end
+
+    def weave_allowed?(from_x, from_y, thru_x, thru_y, direction) #:nodoc:
+      # disallow a weave if there is already a weave at this cell
+      return false if @cells[thru_y][thru_x] & UNDER != 0
+
+      pass_thru = exit_wound(direction, thru_x % 2 != 0)
+      out_x, out_y = move(thru_x, thru_y, pass_thru)
+      return valid?(out_x, out_y) && @cells[out_y][out_x] == 0
+    end
+
+    def perform_weave(from_x, from_y, to_x, to_y, direction) #:nodoc:
+      shifted = to_x % 2 != 0
+      pass_thru = exit_wound(direction, shifted)
+
+      apply_move_at(to_x, to_y, pass_thru << UNDER_SHIFT)
+      apply_move_at(to_x, to_y, AXIS_MAP[shifted][pass_thru] << UNDER_SHIFT)
+
+      nx, ny = move(to_x, to_y, pass_thru)
+      [nx, ny, pass_thru]
+    end
+  end
+end

data/lib/theseus/solvers/astar.rb

@@ -0,0 +1,144 @@
+require 'theseus/solvers/base'
+
+module Theseus
+  module Solvers
+    # An implementation of the A* search algorithm. Although this can be used to
+    # search "perfect" mazes (those without loops), the recursive backtracker is
+    # more efficient in that case.
+    #
+    # The A* algorithm really shines, though, with multiply-connected mazes
+    # (those with non-zero braid values, or some symmetrical mazes). In this case,
+    # it is guaranteed to return the shortest path through the maze between the
+    # two points.
+    class Astar < Base
+
+      # This is the data structure used by the Astar solver to keep track of the
+      # current cost of each examined cell and its associated history (path back
+      # to the start).
+      #
+      # Although you will rarely need to use this class, it is documented because
+      # applications that wish to visualize the A* algorithm can use the open set
+      # of Node instances to draw paths through the maze as the algorithm runs.
+      class Node
+        include Comparable
+
+        # The point in the maze associated with this node.
+        attr_accessor :point
+
+        # Whether the node is on the primary plane (+false+) or the under plane (+true+)
+        attr_accessor :under
+
+        # The path cost of this node (the distance from the start to this cell,
+        # through the maze)
+        attr_accessor :path_cost
+        
+        # The (optimistic) estimate for how much further the exit is from this node.
+        attr_accessor :estimate
+        
+        # The total cost associated with this node (path_cost + estimate)
+        attr_accessor :cost
+        
+        # The next node in the linked list for the set that this node belongs to.
+        attr_accessor :next
+
+        # The array of points leading from the starting point, to this node.
+        attr_reader :history
+
+        def initialize(point, under, path_cost, estimate, history) #:nodoc:
+          @point, @under, @path_cost, @estimate = point, under, path_cost, estimate
+          @history = history
+          @cost = path_cost + estimate
+        end
+
+        def <=>(node) #:nodoc:
+          cost <=> node.cost
+        end
+      end
+
+      # The open set. This is a linked list of Node instances, used by the A*
+      # algorithm to determine which nodes remain to be considered. It is always
+      # in sorted order, with the most likely candidate at the head of the list.
+      attr_reader :open
+
+      def initialize(maze, a=maze.start, b=maze.finish) #:nodoc:
+        super
+        @open = Node.new(@a, false, 0, estimate(@a), [])
+        @visits = Array.new(@maze.height) { Array.new(@maze.width, 0) }
+      end
+
+      def current_solution #:nodoc:
+        @open.history + [@open.point]
+      end
+
+      def step #:nodoc:
+        return false unless @open
+
+        current = @open
+
+        if current.point == @b
+          @open = nil
+          @solution = current.history + [@b]
+        else
+          @open = @open.next
+
+          @visits[current.point[1]][current.point[0]] |= current.under ? 2 : 1
+
+          cell = @maze[current.point[0], current.point[1]]
+
+          directions = @maze.potential_exits_at(current.point[0], current.point[1])
+          directions.each do |dir|
+            try = current.under ? (dir << Theseus::Maze::UNDER_SHIFT) : dir
+            if cell & try != 0
+              point = move(current.point, dir)
+              next unless @maze.valid?(point[0], point[1])
+              under = ((@maze[point[0], point[1]] >> Theseus::Maze::UNDER_SHIFT) & @maze.opposite(dir) != 0)
+              add_node(point, under, current.path_cost+1, current.history + [current.point])
+            end
+          end
+        end
+
+        return current
+      end
+
+      private
+
+      def estimate(pt) #:nodoc:
+        Math.sqrt((@b[0] - pt[0])**2 + (@b[1] - pt[1])**2)
+      end
+
+      def add_node(pt, under, path_cost, history) #:nodoc:
+        return if @visits[pt[1]][pt[0]] & (under ? 2 : 1) != 0
+
+        node = Node.new(pt, under, path_cost, estimate(pt), history)
+
+        if @open
+          p, n = nil, @open
+
+          while n && n < node
+            p = n
+            n = n.next
+          end
+
+          if p.nil?
+            node.next = @open
+            @open = node
+          else
+            node.next = n
+            p.next = node
+          end
+
+          # remove duplicates
+          while node.next && node.next.point == node.point
+            node.next = node.next.next
+          end
+        else
+          @open = node
+        end
+      end
+
+      def move(pt, direction) #:nodoc:
+        [pt[0] + @maze.dx(direction), pt[1] + @maze.dy(direction)]
+      end
+    end
+  end
+end