Educational Objectives: After completing this assignment, the student should be able to accomplish the following:
Operational Objectives: Design and implement a simulation that receives as input a rectangular 2-dimensional maze along with "begin" and "goal" locations in the maze and produces a path through the maze from "begin" to "goal" using breadth-first search.
Deliverables: Four (4) files: maze.h, maze.cpp, mymaze, and log.txt.
A maze file is designed to describe a maze problem as defined above. The file consists of unsigned integers that may be in any format in the file but are typically arranged to mimic the actual arrangement of cells in the maze problem. Your program should read maze data from an external file, assuming the following file format:
numrows numcols (first row of codes) (second row of codes) ... (last row of codes) start goal [optional documentation or other data may be placed here]
We will refer to such a file as a maze file. (Note that the actual format is optional, for human readability. The file is syntactically correct as long as there are the correct number of (uncorrupted) unsigned integer entries.)
A maze file is interpreted as follows:
numrows and numcols are the number of rows and columns, respectively, in the maze.
Each entry in a row of codes (after numrows and numcols but before start and goal) is a decimal integer code in the range [0..15]. The code is interpreted as giving the "walls" in the cell. We will refer to this as a walls code. A specific walls code is interpreted by looking at the binary representation of the code, with 1's bit = North wall, 2's bit = East wall, 4's bit = South wall, and 8's bit = West wall. (Interpret "up" as North when drawing pictures.) A bit value of 1 means the wall exists. A bit value of 0 means the wall does not exist. For example walls code 13 means a cell with North, South, and West walls but no East wall, because (13)10 = 8 + 4 + 1 = (1101)2 (2's bit is unset).
Cells are numbered consecutively from left to right and top to bottom, beginning with cell 0 at the upper left. (Thus, a 4x6 maze has cells 0,1,2,...,23.) We refer to these as cell numbers. start and goal are cell numbers (NOT walls codes). They inform where the maze starting location is and where the goal lies.
The optional data following goal is treated as file documentation (i.e., ignored).
Work within your subdirectory cop4530/proj1. The usual COP 4530 rules apply, as explained in Chapter 1 of the Lecture Notes.
From the course library directory LIB, copy the following files into your project directory:
LIB/proj1/proj1submit.sh # submit script LIB/proj1/maze.startHere # start for maze.h LIB/proj1/ratpack.cpp # maze client LIB/proj1/mazetest.cpp # maze client LIB/proj1/maze* # example maze files LIB/proj1/badmaze* # more maze files LIB/proj1/makefile # builds project and individual components
Begin by copying maze.startHere to maze.h. Edit maze.h appropriately, at the very least by personalizing the file header.
Create the files maze.cpp, and mymaze adhering to the requirements and specifications below. NOTE: a makefile is distributed. It should not need modification.
Turn in files maze.h, maze.cpp, mymaze, and log.txt using the submit script LIB/proj1/proj1submit.sh.
Warning: Submit scripts do not work on the program and linprog servers. Use shell.cs.fsu.edu to submit projects. If you do not receive the second confirmation with the contents of your project, there has been a malfunction.
Solution Framework. Your solution should be based on the framework distributed in the files proj1/maze.h.startHere and maze.cpp.starthere. This framework consists of two classes, Maze and Cell.
Maze API (Maze public member functions)
Maze internal representation
A Maze object can hold one internal maze representation, read from a maze file. Class Maze is designed to be a singleton: only one Maze object exists in a given execution environment. Use of a copy constructor and assignment operator by client is prohibited. Maze data is as follows:
private: // variables unsigned long numrows_, numcols_; Cell * start_; Cell * goal_; fsu::Vector < Cell > cellVector_; // cell inventory fsu::Queue < Cell* , fsu::Deque < Cell* > > conQueue_; // control queue
numrows_ and numcols_ store the dimensions of the maze.
cellVector_ is used to store actual Cell objects that make up a maze. Cell objects should not be copied.
start_ and goal_ point to the start and goal cells (in the cell inventory).
conQueue_ is the principal control structure for the maze solver algorithm. Note that conQueue_ stores pointers to Cell objects; cell objects reside in the cell inventory.
No data members may be added to class Maze.
Cell API (Cell public member functions)
Cell internal representation
A Cell object represents one square in a maze, including knowledge of what cells are neighbors. Cell facilitates the maze search algorithm by providing a visited flag and methods that detect neighbors and select a next unvisited neighbor.
private: // variables unsigned long id_; bool visited_; fsu::List < Cell* > neighborList_;
id_ is the name (cell number) of the cell
neighborList_ is a list of (pointers to) cells that are adjacent to this cell in the maze
visited_ is a flag indicating whether a cell has been visited
No data members may be added to class Cell
Internal functionality
bool Maze::Initialize(char*)
Reads data from a maze file and sets up the internal representation of the maze problem. The complete internal representation of a maze problem is established, including the maze dimensions, cell inventory (with neighborlists for each cell), and start/goal. Checks the maze file syntax while reading. Returns true when read is successful. The following should be checked as the file is read:
bool Maze::Consistent() const
Checks the internal representation of a maze (previously established by Initialize()), detecting and reporting situations where the representation is not self-consistent. Returns true when no inconsistencies are found. The following logic errors should be caught ([R] = required, [O] = optional):
void Maze::Solve(fsu::List<unsigned long>& solution)
Uses breadth-first-search (facilitated by conQueue) to find a solution to the internally represented maze problem. Once the problem is solved, the solution is placed in the list solution passed in by the client program.
void Maze::ShowMaze(std::ostream&) const
Produces a graphic of the maze using the internal representation.
void Cell::AddNeighbor (Cell * N)
Adds a (pointer to) a new neighbor cell of this cell.
Cell* Cell::GetNextNeighbor () const
Returns (pointer to) this cell's next unvisited neighbor. Returns 0 if
this has no unvisited neighbors.
bool Cell::IsNeighbor (const Cell * c) const
Returns true if c is (the address of) a neighbor of this cell.
Various data accessors and manipulators
Required to be used for safe programming practice when implementing
Maze methods.
Required elements.
There is one tight coupling: function Maze::Consistent is a friend of the Cell class. This facilitates the consistency check using internal maze and cell data. All other Maze methods operate through the Cell API.
No data members may be added to class Maze or class Cell.
Walls codes may not be stored in Maze or Cell objects. Walls codes may only be stored in local variables of method Initialize().
Do not use recursion.
Private methods may be added to Maze as desired, but no methods should be added to Cell.
A minimum functioning solution consists of methods Initialize() and Solve() operating correctly on correct maze files. (This is the 80 point level.)
An advanced solution also implements method Consistent() and operates correctly on both correct maze files and improperly configured maze files. (This is the full 100 point level.)
Up to 20 extra credit project points may be earned for implementation of method ShowMaze(). Note: To get the full 20 points extra credit for ShowMaze(), you have to do something more creative than is illustrated in therat.x and mazetest.x [option 4]. If you do that exactly, you can get 10 extra credit points. Some 20 point solutions are illustrated in mazetest.x [options 5,6], but the possibilities are limited only by your imagination.
One maze file mymaze of your own creation is required. (That is, it should not be based on any distributed files and should not be obtained from another source). Your mymaze should be a (correctly configured) representation of a maze problem (1) with at least 5 rows and 6 columns, (2) with more than one solution, and (3) such that all solutions are at least 20 steps in length.
Note that all of the Maze methods are distributed with "stub" implementations, so that the project will build as distributed (with a few warnings about unused function arguments). Be sure that your submission builds correctly with the distributed makefile, therat.cpp, and mazetest.cpp, even if you are submitting without full implementations of all the methods.
Review of deliverables:
maze.h and maze.cpp define and implement classes Maze and Cell
mymaze is a maze file of your own creation
log.txt work and testing log
Begin the project by creating a few maze files. Recommended practice: put an ascii graphic of the maze in the maze file, following the maze file data. Use LIB/area51/therat.x or LIB/area51/mazetest.x to check out your maze files.
Recommended order of implementation of methods:
Think of the cell vector as a master inventory of cells. All other references to cells point into this inventory (rather than making copies of cells). "Point" with pointers, not indices.
Assuming that number, row, col are unsigned long, the
number of a cell is obtainable from its row, col indices as
number = row * numcols + col;
Similarly, if you know the cell
number then you can find it's row, col indices from the cell
number as
row = number / numcols; col = number % numcols;
Now ask yourself: what are the numbers of the neighbors to the North, East,
South, and West?
A walls code of a cell is easily converted to see which neighbor cells are accessible. For example, to see whether cellVector[number] has an accessible neighbor to the West, do something like
if ((0 < col) && ((walls & 0x08) == 0))
{//add the West neighbor to the neighbor list}
Sample executables therat.x and mazetest.x will be available in area51.
You may also enjoy the defective version area51/badpack.x.
Dont forget: You will be graded on what you submit that works. If your submission doesn't compile, or if you don't compile a particular functionality, you will be graded accordingly.