theseus 1.0.0

data/README.rdoc

@@ -0,0 +1,137 @@
+= Theseus
+
+Theseus is a library for generating and solving mazes. It also includes
+routines for rendering mazes (and their solutions) to both ASCII art,
+and to PNG image files.
+
+There is also an included utility for generating mazes from the command-line.
+
+Note that Theseus requires Ruby 1.9.2 or higher.
+
+== Overview
+
+Theseus supports the following types of mazes:
+
+* *Orthogonal*. This is the traditional maze layout of rectangular passages.
+* *Delta*. This maze type tesselates the field into triangles.
+* *Sigma*. The field is tesselated into hexagons.
+* *Upsilon*. The maze field consists of tiled octogons and squares.
+
+Mazes may be generated using any of the following features:
+
+* *Symmetry*. The maze may be reflected in x, y, x and y, or radially. (Not
+  all maze types support symmetry yet.)
+* *Randomness*.  A maze with low randomness will result in many long, straight
+  corridors. Higher randomness gives a maze with more twists and turns.
+* *Weave*. Mazes with high weave will frequently pass over or under existing
+  passages. Low weave mazes will prefer to remain on the same plane.
+* *Braid*. Mazes with high braid will trade dead-ends for circular loops in
+  the maze. Thus, braided mazes will tend to have multiple possible solutions.
+* *Wrap*. Mazes may wrap in x, y, or x and y together. A maze that wraps in
+  any of its dimensions will allow the passages to go from one side
+  of the maze to the other, by moving beyond the far edge of the
+  maze. Another way to think of it is that a maze that wraps in one
+  dimension may be mapped onto a cylinder, and a maze that wraps in
+  both dimensions may be mapped onto a torus.
+* *Masks*. Mazes may be constrained with masks, which are basically boolean
+  grids that define where a passage is allowed to exist. With masks,
+  you can create mazes that fit pre-defined geometry, or wrap around text.
+
+Theseus supports the following output types:
+
+* *ASCII*. Using the ASCII output, you can simply print a maze to the console
+  to see what it looks like. Not all features can be displayed well
+  in ASCII mode, but it works well enough to see what the maze will be like.
+* *PNG*. Mazes that are rendered to PNG may be highly customized, and even
+  allow you to specify custom paths to be rendered.
+
+Theseus supports the following solution algorithms:
+
+* <b>Recursive Backtracking</b>. This is a fast, efficient algorithm for solving
+  mazes that have no circular loops (e.g. unbraided mazes).
+* <b>A* Search</b>. The A* search algorithm really shines with mazes that
+  are highly braided, and is guaranteed to provide you with the shortest
+  path through the maze.
+
+Orthogonal mazes may be converted to their _unicursal_ equivalent. A unicursal
+maze is one which has only a single path that covers every cell in the field
+exactly once. This style is maze is often called a "labyrinth". See
+Theseus::OrthogonalMaze#to_unicursal for more information.
+
+Theseus is also designed to allow you to step through both the generation of
+the maze, as well as the computation of the solution. This lets you (for instance)
+animate the construction (and solution) of the maze by drawing individual PNG
+frames for each step! And since Theseus includes an implementation of A* Search,
+this gives you an interesting way to visualize (among other things) how that
+algorithm works.
+
+Lastly, Theseus can be used to manually build mazes (or any other grid-based
+structure) by hand. See Theseus::Maze for more information.
+
+== Usage
+
+Theseus is designed to be super simple to use. Here are some examples:
+
+  require 'theseus'
+
+  # generate a 10x10 orthogonal maze and print it to the console
+  maze = Theseus::OrthogonalMaze.generate(width: 10)
+  puts maze
+
+  # render a triangular delta maze to a PNG file
+  maze = Theseus::DeltaMaze.generate(mask: Theseus::TriangularMask.new(10))
+  File.open("triangle.png", "w") { |f| f.write(maze.to(:png)) }
+
+  # render a highly braided, hexagonally-tiled maze, with its solution
+  maze = Theseus::SigmaMaze.generate(width: 20, height: 20, braid: 100)
+  File.open("sigma.png", "w") do |f|
+    f.write(maze.to(:png, solution: true))
+  end
+
+  # poor-man's animation of the generation of an octogon/square-tiled maze
+  maze = Theseus::UpsilonMaze.new(width: 10)
+  while maze.step
+    puts maze
+    sleep 0.05
+  end
+  puts maze
+
+  # emit animation frames showing the solution of a maze
+  maze = Theseus::OrthogonalMaze.generate(width: 10)
+  solver = maze.new_solver
+  step = 0
+  solver.each do
+    File.open("frame-%04d.png" % step, "w") do |f|
+      path = solver.to_path(color: 0xff0000ff)
+      f.write(maze.to(:png, paths:[path]))
+    end
+    step += 1
+  end
+
+See the documentation for Theseus::Maze for information on all of these
+features.
+
+To use the command-line utility, simply pass the -h flag to the "theseus"
+utility on the command-line:
+
+  $ theseus -h
+
+== Requirements
+
+Theseus requires Ruby 1.9.2, and the ChunkyPNG library.
+
+== Installation
+
+To install, simply type:
+
+  gem install theseus
+
+This will install both the library, as well as the command-line "theseus"
+tool.
+
+== License
+
+Theseus is created by Jamis Buck. It is made available in the public domain,
+completely unencumbered by rules, restrictions, or any other nonsense.
+
+Please prefer good over evil.

data/Rakefile

@@ -0,0 +1,42 @@
+require 'rake'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/testtask'
+
+require './lib/theseus/version'
+
+task :default => :test
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList["test/*.rb"]
+  t.verbose = true
+end
+
+spec = Gem::Specification.new do |s|
+  s.platform = Gem::Platform::RUBY
+  s.summary = "Maze generator for Ruby"
+  s.name = 'theseus'
+  s.version = Theseus::Version::STRING
+  s.files = FileList["README.rdoc", "Rakefile", "lib/**/*.rb", "examples/**/*.rb", "bin/*", "test/**/*.rb"].to_a
+  s.executables << "theseus"
+  s.add_dependency "chunky_png", "~> 0.12.0"
+  s.requirements << "Ruby 1.9"
+  s.description = "Theseus is a library for building random mazes."
+  s.author = "Jamis Buck"
+  s.email = "jamis@jamisbuck.org"
+  s.homepage = "http://github.com/jamis/theseus"
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.need_zip = true
+  pkg.need_tar = true
+end
+
+Rake::RDocTask.new do |rd|
+  rd.main = "README.rdoc"
+  rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
+end
+
+task :clean do
+ rm_rf ["html", "pkg"]
+end

data/bin/theseus

@@ -0,0 +1,262 @@
+#!/usr/bin/env ruby
+
+require 'optparse'
+require 'theseus'
+require 'theseus/formatters/png'
+
+type_map = {
+  "ortho"   => Theseus::OrthogonalMaze,
+  "delta"   => Theseus::DeltaMaze,
+  "sigma"   => Theseus::SigmaMaze,
+  "upsilon" => Theseus::UpsilonMaze
+}
+
+animate = false
+output = "maze"
+sparse = 0
+unicursal = false
+type = "ortho"
+format = :ascii
+
+png_opts = Theseus::Formatters::PNG::DEFAULTS.dup
+maze_opts = { mask: nil, width: nil, height: nil,
+  randomness: 50, weave: 0, symmetry: :none, braid: 0, wrap: :none,
+  entrance: nil, exit: nil }
+
+OptionParser.new do |opts|
+  opts.separator ""
+  opts.separator "Required options:"
+
+  opts.on("-w", "--width N", Integer, "width of the maze (default 20, or mask width)") do |w|
+    maze_opts[:width] = w
+  end
+
+  opts.on("-H", "--height N", Integer, "height of the maze (default 20 or mask height)") do |h|
+    maze_opts[:height] = h
+  end
+
+  opts.on("-m", "--mask FILE", "png file to use as mask") do |m|
+    case m
+    when /^triangle:(\d+)$/ then maze_opts[:mask] = Theseus::TriangleMask.new($1.to_i)
+    else maze_opts[:mask] = Theseus::Mask.from_png(m)
+    end
+  end
+
+  opts.separator ""
+  opts.separator "Output options:"
+
+  opts.on("-a", "--[no-]animate", "emit frames for each step") do |v|
+    animate = v
+  end
+
+  opts.on("-o", "--output FILE", "where to save the file(s) (for png only)") do |f|
+    output = f
+  end
+
+  opts.on("-f", "--format FMT", "png, ascii (default #{format})") do |f|
+    format = f.to_sym
+  end
+
+  opts.on("-V", "--solve [METHOD]", "whether to display the solution of the maze.", "METHOD is either `backtracker' (the default) or `astar'") do |s|
+    png_opts[:solution] = (s || :backtracker).to_sym
+  end
+
+  opts.separator ""
+  opts.separator "Maze options:"
+
+  opts.on("-s", "--seed N", Integer, "random seed to use") do |s|
+    srand(s)
+  end
+
+  opts.on("-t", "--type TYPE", "#{type_map.keys.sort.join(",")} (default: #{type})") do |t|
+    type = t
+  end
+
+  opts.on("-u", "--[no-]unicursal", "generate a unicursal maze (results in 2x size)") do |u|
+    unicursal = u
+  end
+
+  opts.on("-y", "--symmetry TYPE", "one of none,x,y,xy,radial (default is '#{maze_opts[:symmetry]}')") do |s|
+    maze_opts[:symmetry] = s.to_sym
+  end
+
+  opts.on("-e", "--weave N", Integer, "0-100, chance of a passage to go over/under another (default #{maze_opts[:weave]})") do |v|
+    maze_opts[:weave] = v
+  end
+
+  opts.on("-r", "--random N", Integer, "0-100, randomness of maze (default #{maze_opts[:randomness]})") do |r|
+    maze_opts[:randomness] = r
+  end
+
+  opts.on("-S", "--sparse N", Integer, "how sparse to make the maze (default #{sparse})") do |s|
+    sparse = s
+  end
+
+  opts.on("-d", "--braid N", Integer, "0-100, percentage of deadends to remove (default #{maze_opts[:braid]})") do |b|
+    maze_opts[:braid] = b
+  end
+
+  opts.on("-R", "--wrap axis", "none,x,y,xy (default #{maze_opts[:wrap]})") do |w|
+    maze_opts[:wrap] = w.to_sym
+  end
+
+  opts.on("-E", "--enter [X,Y]", "the entrance of the maze (default -1,0)") do |s|
+    maze_opts[:entrance] = s.split(/,/).map { |v| v.to_i }
+  end
+
+  opts.on("-X", "--exit [X,Y]", "the exit of the maze (default width,height-1)") do |s|
+    maze_opts[:exit] = s.split(/,/).map { |v| v.to_i }
+  end
+
+  opts.separator ""
+  opts.separator "Formatting options:"
+
+  opts.on("-B", "--background COLOR", "rgba hex background color for maze (default %08X)" % png_opts[:background]) do |c|
+    png_opts[:background] = c
+  end
+
+  opts.on("-C", "--cellcolor COLOR", "rgba hex cell color for maze (default %08X)" % png_opts[:cell_color]) do |c|
+    png_opts[:cell_color] = c
+  end
+
+  opts.on("-L", "--wallcolor COLOR", "rgba hex wall color for maze (default %08X)" % png_opts[:wall_color]) do |c|
+    png_opts[:wall_color] = c
+  end
+
+  opts.on("-U", "--solutioncolor COLOR", "rgba hex color for the answer path (default %08X)" % png_opts[:solution_color]) do |c|
+    png_opts[:solution_color] = c
+  end
+
+  opts.on("-c", "--cell N", Integer, "size of each cell (default #{png_opts[:cell_size]})") do |c|
+    png_opts[:cell_size] = c
+  end
+
+  opts.on("-b", "--border N", Integer, "border padding around outside (default #{png_opts[:outer_padding]})") do |c|
+    png_opts[:outer_padding] = c
+  end
+
+  opts.on("-p", "--padding N", Integer, "padding around cell (default #{png_opts[:cell_padding]})") do |c|
+    png_opts[:cell_padding] = c
+  end
+
+  opts.on("-W", "--wall N", Integer, "thickness of walls (default #{png_opts[:wall_width]})") do |c|
+    png_opts[:wall_width] = c
+  end
+
+  opts.separator ""
+  opts.separator "Other options:"
+
+  opts.on_tail("-v", "--version", "display the Theseus version and exit") do
+    maze = Theseus::OrthogonalMaze.generate(width: 20, height: 4)
+    s = maze.to_s(mode: :lines).strip
+    print s.gsub(/^/, "          ").sub(/^\s*/, "theseus --")
+
+    require 'theseus/version'
+    puts "--> v#{Theseus::Version::STRING}"
+    puts "a maze generator, renderer, and solver by Jamis Buck <jamis@jamisbuck.org>"
+    exit
+  end
+
+  opts.on_tail("-h", "--help", "this helpful list of options") do
+    puts opts
+    exit
+  end
+end.parse!
+
+# default width to height, and vice-versa
+maze_opts[:width] ||= maze_opts[:height]
+maze_opts[:height] ||= maze_opts[:width]
+
+if maze_opts[:mask].nil? && (maze_opts[:width].nil? || maze_opts[:height].nil?)
+  warn "You must specify either a mask (-m) or the maze dimensions(-w or -H)."
+  abort "Try --help for a full list of options."
+end
+
+if animate
+  abort "sparse cannot be used for animated mazes" if sparse > 0
+  abort "cannot animate unicursal mazes" if unicursal
+
+  png_opts[:background] = ChunkyPNG::Color.from_hex(png_opts[:background]) unless Fixnum === png_opts[:background]
+  solution = png_opts.delete(:solution)
+
+  if png_opts[:background] & 0xFF != 0xFF
+    warn "if you intend to make a movie out of the frames from the animation,"
+    warn "it is HIGHLY RECOMMENDED that you use a fully opaque background color."
+  end
+end
+
+if unicursal
+  unicursal_entrance = maze_opts.delete(:entrance)
+  maze_opts[:entrance] = [0,0]
+  maze_opts[:exit] = [0,0]
+end
+
+maze_opts[:mask] ||= Theseus::TransparentMask.new(maze_opts[:width], maze_opts[:height])
+maze_opts[:width] ||= maze_opts[:mask].width
+maze_opts[:height] ||= maze_opts[:mask].height
+maze = type_map[type].new(maze_opts)
+
+if unicursal && !maze.respond_to?(:to_unicursal)
+  abort "#{type} mazes do not support the -u (unicursal) option"
+end
+
+if animate
+  step = 0
+  maze.generate! do
+    if format == :ascii
+      system "clear"
+      puts maze.to_s(:mode => :utf8_halls)
+      sleep 0.05
+    else
+      f = "%s-%04d.png" % [output, step]
+      step += 1
+      File.open(f, "w") { |io| io.write(maze.to(:png, png_opts)) }
+      print "."
+    end
+  end
+
+  if format == :ascii
+    system "clear"
+    puts maze.to_s(:mode => :utf8_halls)
+  else
+    f = "%s-%04d.png" % [output, step]
+    File.open(f, "w") { |io| io.write(maze.to(:png, png_opts)) }
+    print "."
+
+    if solution
+      solver = maze.new_solver(type: solution)
+
+      while solver.step
+        path = solver.to_path(color: png_opts[:solution_color])
+
+        step += 1
+        f = "%s-%04d.png" % [output, step]
+        File.open(f, "w") { |io| io.write(maze.to(:png, png_opts.merge(paths: [path]))) }
+        print "."
+      end
+    end
+
+    puts
+    puts "done, %d frames written to %s-*.png" % [step+1, output]
+  end
+else
+  maze.generate!
+  sparse.times { maze.sparsify! }
+
+  if unicursal
+    enter_at = unicursal_entrance || [-1,0]
+    if enter_at[0] > 0 && enter_at[0] < width*2
+      exit_at = [enter_at[0]+1, enter_at[1]]
+    else
+      exit_at = [enter_at[0], enter_at[1]+1]
+    end
+    maze = maze.to_unicursal(entrance: enter_at, exit: exit_at)
+  end
+
+  if format == :ascii
+    puts maze.to_s(:mode => :utf8_halls)
+  else
+    File.open(output + ".png", "w") { |io| io.write(maze.to(:png, png_opts)) }
+    puts "maze written to #{output}.png"
+  end
+end

data/examples/a-star-search.rb

@@ -0,0 +1,106 @@
+# Demonstrates the following features of Theseus:
+#
+# * the A* solver algorithm
+# * using Theseus::Path objects to customize the render
+# * stepping through the solution process in order to animate it
+#   (by spitting out a new frame for each step)
+
+require 'theseus'
+
+# use 100% braid, to give a completely multiple-connected maze
+# which will show the A* search to best effect (returning not
+# just any path through the maze, but the SHORTEST path)
+maze = Theseus::OrthogonalMaze.new(width: 15, height: 15, braid: 100)
+
+puts "generating the maze..."
+maze.generate!
+
+# get a new solver object using the A* search algorithm.
+solver = maze.new_solver(type: :astar)
+puts "solving the maze..."
+
+step = 0
+renderings = 0
+
+# use a path object to record every attempted route. This is how we'll
+# show "stale" paths that the algorithm determined were ineffecient.
+stale_paths = maze.new_path(color: 0x9f9f9fff)
+
+while solver.step
+  # the open_set path will show all points in the "open set", the sorted
+  # set of points that A* uses to determine where to search next.
+  open_set = maze.new_path(color: 0xaaffaaff)
+
+  # the histories path shows the routes leading up to each point in the
+  # open set.
+  histories = maze.new_path(color: 0xaaaaffff)
+
+  # the "best" path is the path that the algorithm currently considers
+  # the most promising lead.
+  best = maze.new_path(color: 0xffaaaaff)
+
+  # begin with the first node in the open set
+  n = solver.open
+
+  while n
+    # add the point itself to the open_set path
+    open_set.set(n.point)
+
+    # iterate over the node's history and add add the appropriate
+    # connections to the "histories" path
+    prev = maze.entrance
+    n.history.each do |pt|
+      how = histories.link(prev, pt)
+      histories.set(pt, how)
+      prev = pt
+    end
+    how = histories.link(prev, n.point)
+    histories.set(n.point, how)
+    n = n.next
+  end
+
+  if solver.open
+    prev = maze.entrance
+    solver.open.history.each do |pt|
+      how = best.link(prev, pt)
+      best.set(pt, how)
+      prev = pt
+    end
+    best.link(prev, solver.open.point)
+  elsif solver.solved?
+    prev = maze.entrance
+    solver.solution.each do |pt|
+      how = best.link(prev, pt)
+      best.set(pt, how)
+      prev = pt
+    end
+    best.link(prev, maze.exit)
+  end
+
+  # add all previously examined histories to the stale paths.
+  stale_paths.add_path(histories)
+
+  # try to keep at least 6 frames animating in the background, to speed
+  # things along.
+
+  while renderings > 6
+    Process.wait
+    renderings -= 1
+  end
+
+  renderings += 1
+
+  fork do
+    File.open("step-%04d.png" % step, "w" ) do |f|
+      f.write(maze.to(:png, cell_size: 20, background: 0x2f2f2fff, paths: [best, open_set, histories, stale_paths]))
+    end
+  end
+
+  puts "%d..." % step
+  step += 1
+end
+
+while renderings > 0
+  Process.wait
+  renderings -= 1
+end