Browse files

rdoc overview

  • Loading branch information...
1 parent f374ff8 commit 3fc4b503ccf6f7186bfcf351a4e85884ed4de047 @jamis committed Dec 19, 2010
Showing with 139 additions and 66 deletions.
  1. +0 −65 README.markdown
  2. +137 −0 README.rdoc
  3. +2 −1 Rakefile
View
65 README.markdown
@@ -1,65 +0,0 @@
-Theseus
-=======
-
-Theseus is a maze generation library for Ruby. It's features are:
-
-* Generate mazes with a single line of code.
-* Easily animate the process of building the maze.
-* Display the solution to a generated maze.
-* Output the maze as either text or PNG.
-* Apply a mask to the process to constrain how the maze is built.
-* Culling dead-ends from a maze to increase its sparseness.
-* Convert any orthogonal maze to a unicursal (labyrinth-style) maze.
-* Generate mazes with high braid or low braid (or anything in-between). (a "perfectly braided" maze is completely multiply-connected, with no dead-ends and circular paths)
-* Generate mazes with high weave or low weave (or anything in-between). ("weave" refers to how frequently passages move under or over existing passages.)
-* Generate mazes with various types of symmetry (x, y, xy, radial)
-* Various maze types, including:
- * orthogonal (the default). Square cells with 4 exits each.
- * delta. Triangular cells with 3 exits each.
- * sigma. Hexagonal cells with 6 exits each.
- * upsilon. Octagonal and square cells with 8 or 4 exits each.
-
-Requirements
-============
-
-* Ruby 1.9
-* ChunkyPNG library
-
-Installation
-============
-
- gem install theseus
-
-Usage
-=====
-
-The gem installs a command that may be used to generate mazes from the
-command-line:
-
- $ theseus -w 10 -H 10
-
-The above command would generate a 10x10 maze and write it out to "maze.png".
-Pass the "-h" option for a list of all supported options.
-
-Alternatively, you can build the mazes programmatically:
-
- require 'theseus/orthogonal_maze'
-
- maze1 = Theseus::OrthogonalMaze.generate(10, 10)
- File.open("maze.png", "w") { |f| f.write(maze1.to(:png)) }
-
- mask = Theseus::Mask.from_png("mask.png")
- maze2 = Theseus::OrthogonalMaze.new(mask.width, mask.height, weave: 50,
- randomness: 100, mask: mask)
- n = 0
- while maze2.step
- File.open("frame-%04d.png" % n, "w") { |f| f.write(maze2.to(:png)) }
- n += 1
- end
-
-License
-=======
-
-Theseus is a creation of Jamis Buck, who has placed it in the public domain.
-The code may be taken and put to whatever nefarious use you might desire,
-without restriction.
View
137 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.
View
3 Rakefile
@@ -23,5 +23,6 @@ Rake::GemPackageTask.new(spec) do |pkg|
end
Rake::RDocTask.new do |rd|
- rd.rdoc_files.include("lib/**/*.rb")
+ rd.main = "README.rdoc"
+ rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
end

0 comments on commit 3fc4b50

Please sign in to comment.