PR Quadtree Project for CS 3114 · 2020. 10. 12. · CS 3114 Data Structures and Algorithms Project...

CS 3114 Data Structures and Algorithms Project 3: PR Quadtree Generic

Version 6.00 This is a purely individual assignment! 1

PR Quadtree

This assignment involves implementing a point-region quadtree (specifically the PR quadtree as described in section 3.2 of

Samet’s paper) as a Java generic. This data structure will play a vital role in your solution to the next project.

Design and Implementation Requirements

There are some explicit requirements, stated in the header comments for prQuadtree and in the header comments for

some of the specified public methods, in addition to those on the Programming Standards page of the course website.

Your implementation must conform to those requirements. In addition, none of the specified prQuadtree member

functions should write output.

You may safely add features to the given interface, but if you omit or modify members of the given interface you will almost

certainly face compilation errors when you submit your implementation for testing.

You must implement all tree traversals recursively, not iteratively. You will certainly need to add a number of private

recursive helper functions that are not shown above. Since those will never be called directly by the test code, the interfaces

are up to you.

You must place the declaration of your PR quadtree tree generic in a package named cs3114.J3.DS and specify public

and package access for members as indicated in the interface specification, or compilation will fail when you submit it.

Design and Implementation Suggestions

In most cases, the public functions shown in the PR quadtree interface will be little more than stubs that call recursive

private helper functions. This is the standard pattern for implementation, and it is natural, since the recursive traversals

require a parameter that points to a tree node (and the client who makes calls to the public function will not possess any

such pointer).

Some operations can fail. The client may attempt to find a value that doesn't occur in the tree, or may attempt to insert a

value that already occurs in the tree (our version of the PR quadtree will not insert duplicate values). When an operation fails,

it should not do so silently, and so the public functions will return an indicator of success or failure. If the public

function returns a pointer (Java reference), it could simply return null on failure. Otherwise, the public function will

return a Boolean value.

Note that it is never acceptable to perform a needless traversal of the tree; that wastes time and is unnecessary. For example,

insertion logic should never call the public search function, or its private helper, to determine whether the target value

is in the tree, and then perform a second search traversal if the value is absent. Such implementations seem to be fairly

common, perhaps due to a misunderstanding of the purpose of the software engineering goal of avoiding code duplication.



PR Quadtree Interface

Because this assignment will be auto-graded using a test harness we will provide, your implementation must conform to the

public interface below, and include at least all of the public and private members that are shown:

// The test harness will belong to the following package; the quadtree

// implementation must belong to it as well. In addition, the quadtree

// implementation must specify package access for the node types and tree

// members so that the test harness may have access to it.

//

package cs3114.J3.DS;

public class prQuadTree< T extends Compare2D



You may safely add features to the given interface, but if you omit or modify members of the given public interface you will

be likely to face compilation errors when you submit your implementation for testing.

You must implement tree traversals recursively, not iteratively. You will certainly need to add a number of private recursive

helper functions that are not shown above. Since those will never be called directly by the test code, the interfaces are up to

you.

For this assignment, the bucket size is 1; that is, each leaf node will store exactly one data object. That said, you must still use

an ArrayList object to store the single data element in the leaf node; that will help you later when you convert this

implementation to a fully bucketed approach.

Note that the test harness for this assignment is shallower than the one for the BST project. That is, aside from checking the

root pointer, it does not attempt to examine the internal structure of your quadtree at all. Instead, tree displays, written by the

test driver, are compared to determine whether your tree has the correct structure. Therefore, the restrictions on the node

types are extremely flexible.

On the other hand, your implementation must be designed to work with data objects that implement the following interface:


// The interface Compare2D is intended to supply facilities that are useful

// in supporting the use of a generic 2D spatial structure with a user-

// defined data type. As a consequence, the interface contains a number of

// redundant features; it is unlikely that any particular PR quadtree

// implementation would make use of every feature shown here.

//

public interface Compare2D {

// Returns the x-coordinate field of the user data object.

public long getX();

// Returns the y-coordinate field of the user data object.

public long getY();

// Returns indicator of the direction to the user data object from the

// location (X, Y) specified by the parameters.

// The indicators are defined in the enumeration Direction, and are used

// as follows:

//

// NE: vector from (X, Y) to user data object has a direction in the

// range [0, 90) degrees (relative to the positive horizontal axis

// NW: same as above, but direction is in the range [90, 180)

// SW: same as above, but direction is in the range [180, 270)

// SE: same as above, but direction is in the range [270, 360)

// NOQUADRANT: location of user data object is equal to (X, Y)

//

public Direction directionFrom(long X, long Y);

// Returns indicator of which quadrant of the rectangle specified by the

// parameters that user data object lies in.

// The indicators are defined in the enumeration Direction, and are used

// as follows, relative to the center of the rectangle:

//

// NE: user data object lies in NE quadrant, including non-negative

// x-axis, but not the positive y-axis

// NW: user data object lies in the NW quadrant, including the

// positive y-axis, but not the negative x-axis

// SW: user data object lies in the SW quadrant, including the



// negative x-axis, but not the negative y-axis

// SE: user data object lies in the SE quadrant, including the

// negative y-axis, but not the positive x-axis

// NOQUADRANT: user data object lies outside the specified rectangle

//

public Direction inQuadrant(double xLo, double xHi, double yLo,

double yHi);

// Returns true iff the user data object lies within or on the boundaries

// of the rectangle specified by the parameters.

public boolean inBox(double xLo, double xHi, double yLo, double yHi);

}

The interface is intended to allow your implementation to either take coordinates from the data object (via getX() and

getY()) and use those values to make directional decisions, or to use the directionFrom() method supplied by the data

object for the same purpose. The only restriction is that if you take the first approach you must make sure that your logic

follows the following pattern when partitioning the world space:

The actual test data will be created so that (ideally) no data points will ever lie on a region boundary. However, you should

conform to the guideline above just to be safe.

One more note, we specifically require that the equals() and directionFrom() methods are consistent, in the sense

that equals() returns true if and only if directionFrom() returns NOQUADRANT. We are specific about this because

the Java language specification does, in fact, allow an inconsistency between equals() and compareTo().

The Compare2D interface depends upon the following enumerated type:


public enum Direction {NW, SW, SE, NE, NOQUADRANT};

The use of an enumerated type allows us to use descriptive labels at critical points in the implementation. If you have not

made use of this Java feature before, this is a good place to learn about it.

Positive y-axis belongs to the NW quadrant

Positive x-axis belongs to the NE quadrant

Negative y-axis belongs to the SE quadrant

Negative x-axis belongs to the SW quadrant

Center point belongs to the NE quadrant



During our testing of your implementation, we will use the following data object type; a more complete version is posted on

the course website.

package cs3114.J3.Client;

import cs3114.J3.DS.Compare2D;

import cs3114.J3.DS.Direction;

public class Point implements Compare2D {

private long xcoord;

private long ycoord;

public Point() {

xcoord = 0;

ycoord = 0;

}

public Point(long x, long y) {

xcoord = x;

ycoord = y;

}

public long getX() {

return xcoord;

}

public long getY() {

return ycoord;

}

public Direction directionFrom(long X, long Y) { . . . }

public Direction inQuadrant(double xLo, double xHi,

double yLo, double yHi) { . . . }

public boolean inBox(double xLo, double xHi,

double yLo, double yHi) { . . . }

public String toString() { . . . }

public boolean equals(Object o) { . . . }

// Additional methods as needed...

. . .

}

Note that if you use calls to directionFrom()or inQuadrant() or inBox()in your quadtree you must implement

those methods to be consistent with the directional guidelines given on the previous page.

BTW, I put the class Point in the package cs3114.J3.Client because, on the one hand, it needs to be in a package so

my test class can import it, and, on the other hand, it doesn't seem to make sense to put a user data type into a package

intended for data structures.



Test Harness and Grading

We will be testing your implementation with our own test code, which will be posted in a zip file on the course website.

Create a test directory on your system, and unpack the test code zip file there.

gradeJ3.py Python script to automate running test comparisons (Win, macOS)

Note: read comments; must be edited for Linux and/or Eclipse

prQuadGenerator.jar test case generator

LogComparator.jar tool for comparing and scoring test output

./src

testDriver.java main Java file for test harness

cs3114/J3/Client/Point.java data type for insertion into PR quadtree during testing*

cs3114/J3/DS/prQuadtree.java shell for implementing the PR quadtree*

cs3114/J3/DS/Compare2D.java type bound for PR quadtree generic parameter

cs3114/J3/DS/Direction.java enumerated type used in Compare2D

./supplied

cs3114/J3/DS/Lewis.class test methods

* files that you must complete in order to run the testing code

After unpacking the test harness, you must implement the Point and prQuadtree classes in order to perform testing.

Specifically, you must implement the parts of the Point type related to the elements of the Compare2D interface that your

PR quadtree makes use of. You can restrict which methods in the PR quadtree are tested by commenting out sections of the

main test driver file, testDriver.java.

See the README file for an explanation of how to use the testing code.

The supplied test code is thorough, but some edge cases may not occur on every execution of the test code, since it

randomizes the generated test data. You should be sure to run the test code a number of times, using the randomization

feature. For that purpose, you may share test code (but absolutely no tree code!!) via the class Forum.

Be sure you test all of the interface elements thoroughly, both in isolation and in interleaved fashion. Do not include any

testing code in your submission, including calls to JUnit elements.

Using the Generator Tool

The first tool, prQuadGenerator.jar, can be used to create test data and reference results. The tool is designed to be

executed from a command-line environment. Here is a sample session, using a Windows 10 terminal window, that shows the

tool at work. The same approach works on a Linux system. After unpacking the zip file to a directory, open a terminal

window in that directory:

Execute the generator jar file by invoking the Java VM from the command line:

This will create a set of reference log files, based upon random test data, and save the corresponding random seed value in a

file, so it can be used to generate exactly the same data when testing your implementation:

Z:\J3\working > dir

09/17/2020 08:35 PM 16,939 prQuadGenerator.jar

. . .

Z:\J3\working > java -jar prQuadGenerator.jar



Using the Supplied Implementation Framework

The supplied implementation framework is packaged in the zip archive in two directory trees, in a structure that is suitable for

development from the Windows command line, a Linux terminal window, or from Eclipse:

| gradeJ3.py

| LogComparator.jar

| prQuadGenerator.jar

|

+---src

| | testDriver.java

| |

| \---cs3114

| \---J3

| +---Client

| | Point.java

| |

| \---DS

| Compare2D.java

| Direction.java

| prQuadTree.java

|

\---supplied

\---cs3114

\---J3

\---DS

Lewis.class

… from the command line

Unpack the zip archive in a directory; in the discussion below, I have unpacked the archive in a directory named working,

as shown above:

Once you've written your implementations in the files Point.java and prQuadTree.java, You can compile the code

by changing to the subdirectory src, and executing the command shown below [1]:

Z:\J2\working > dir

06/27/2020 09:30 PM cs3114

06/27/2020 09:30 PM supplied

06/27/2020 02:33 PM 14 seed.txt

06/27/2020 02:51 PM 8,498 testDriver.java

Z:\J3\working > dir

09/18/2020 08:17 PM 3,093 gradeJ3.py

08/22/2020 05:01 PM 5,262 LogComparator.jar


09/21/2020 08:51 PM src

09/18/2020 11:50 AM supplied

Z:\J3\working > dir

09/21/2020 08:36 PM 36,113 refTestInsertion.txt

09/21/2020 08:36 PM 4,240 refTestRegionSearch.txt

09/21/2020 08:36 PM 351 refTestTreeInitialization.txt

09/21/2020 08:36 PM 14 seed.txt



The -cp switch lets us specify directories where the Java compiler, javac, will look for resources and .class files. We

provide a semicolon-separated list of directories (the current directory (./) and the directory in which the test code package is

provided (../supplied). For packaged classes, the compiler will then examine the relevant subdirectories. The Java

compiler will accept either '/' or '\' in the path expressions.

If you examine the subdirectories, you should find some new .class files, created by the compiler:

If any of these files are missing, the code did not compile, and you should have seen error messages in the terminal window

that describe the errors. In that case, fix and repeat.

The test driver requires a seed file, created by first running the prQuadGenerator.jar tool, as described earlier. Just

copy the file seed.txt into the same directory as testDriver.class, and then execute the test driver:

Note that you have to specify the classpath again when you run the test driver.

Z:\J3\working > cd src

09/18/2020 11:50 AM cs3114


Z:\J3\working\src > javac -cp ./;../supplied testDriver.java

Z:\J3\working\src > copy ..\seed.txt .

Z:\J3\working\src > java -cp ./;../supplied testDriver

Z:\J3\working > tree /F /A

Folder PATH listing

Volume serial number is 7627-64B6

Z:.

| testDriver.class

| testDriver.java

|

\---cs3114

\---J3

+---Client

| Point.class

| Point.java

|

\---DS

Compare2D.class

Compare2D.java

Direction.class

Direction.java

prQuadTree$1.class

prQuadTree$prQuadInternal.class

prQuadTree$prQuadLeaf.class

prQuadTree$prQuadNode.class

prQuadTree.class

prQuadTree.java



The test driver should create a test log file for each phase of testing:

This created a set of log files, one for each feature test. If the log for a test is missing, or empty, an exception occurred, and

you need to fix that. When in doubt, load test logs into a text editor and see if there are any clues there (like exception

messages or logged error messages from the test driver). Fix and repeat.

The next step is to use the supplied comparison tool to determine your score for each test; that can be done by changing back

to the parent directory (or by copying the log files from .\src into the parent directory):

Executing the comparison tool with no parameters displays instructions:

Invoking the comparison tool on the two node initialization test files:

Repeat the process to evaluate your results for each test that was completed. If you don't get a full score, I suggest redirecting

the output to a file so you can examine it in a text editor.

Z:\J3\working\src > dir

09/18/2020 11:50 AM cs3114

09/21/2020 09:21 PM 14 seed.txt

09/21/2020 09:02 PM 4,702 testDriver.class


09/21/2020 09:21 PM 26,387 TestInsertion.txt

09/21/2020 09:21 PM 3,355 TestRegionSearch.txt

09/21/2020 09:21 PM 285 TestTreeInitialization.txt

Z:\J3\working > java -jar LogComparator.jar 1 refTestTreeInitialization.txt

.\src\TestTreeInitialization.txt

Maximum score 50

checkTreeInitialization results:

Creating a new prQuadtree with world boundaries:

xMin: 0

xMax: 32768

yMin: 0

yMax: 32768

prQuadtree root was OK.

prQuadtree xMin was OK.

prQuadtree xMax was OK.

prQuadtree yMin was OK.

prQuadtree yMax was OK.

1 >> Score: 50.00 / 50.00

Z:\J3\working\src > cd ..

Z:\J3\working > java -jar LogComparator.jar

Invoke: java -jar LogComparator.jar

is necessary for the grading script; you may just use '1' for that.

The reference results file should be created with the posted generator tool.

The student results file should be created by your solution, using the

the input file corresponding to the reference results file.

The order of the file names on the command line does matter.



… from Eclipse

In order to use the supplied implementation framework with Eclipse:

create a new Java project in Eclipse; do not create any files within the project; I called mine prQuadTree

unpack the supplied zip file into the top-level directory for the Eclipse project (not into the src directory!)

This should have created a directory structure like this:

.\prQuadTree

| gradeJ3.py

| LogComparator.jar

| prQuadGenerator.jar

|

+---src

| | testDriver.java

| |

| \---cs3114

| \---J3

| +---Client

| | Point.java

| |

| \---DS

| Compare2D.java

| Direction.java

| prQuadTree.java

\---supplied

\---cs3114

\---J3

\---DS

Lewis.class

Back in Eclipse, with the project open, press the F5 key to refresh the project view. The Package Explorer panel should now

show the subdirectories and files you just added.

Now, right-click on the Project and go to Properties. Then go to Java Build Path and choose the Libraries pane. Select Add

Class Folder… and select the ./supplied folder.



This makes the Eclipse builder aware of the supplied .class file(s). Now, you should be able to compile and execute your

code as usual. Note that if you execute the program from within Eclipse, input files like seed.txt must be placed in the

top-level project folder (where prQuadGenerator.jar is).

Follow the previous instructions to use the comparison tool to check your results.

More on the Comparison Tool

If you notice different data values in the reference and student log files, then you've misused the tools. Whether or not you

are using the Python script to run things, then there are several possibilities, but in the end it comes down to the fact that the

reference logs and the student logs were generated using different seed values.

Normally, I use output redirection, because the comparison tool writes its output to the terminal, and I want to save those

results for easy examination if the score is less than optimal. For example:

That's not very good… notice that some lines show point deductions. The key now is to find the first lines in the results that

show deductions:

OK, the error is obvious; the implementation inserted a duplicate value, but the specification says that should NOT happen.

So, we'd need to fix the implementation (in Point.java or prQuadtree.java), recompile, repeat the test, and then

compare the results again.

. . .

-2.00 --------------- 963

-2.00 --------------------- 968

------------------ 994

Student file has 1 more lines than reference file.

1 >> Score: 42.50 / 301.00

. . .

Try inserting a value, -248, that's already in the tree.

insert() returned false.

Let's see what the tree looks like now:

-2.50 ------ -248

-5.00 --- -248

-5.00 -238

. . .



Using the Script

Of course, you need to check ALL of the results, and that will be tedious since there are many separate test files. So, we've

also supplied a Python script that will automate running the tests and performing the comparisons, if you work from the

command line.

The script is designed for use whether you operate strictly from the command-line or you use Eclipse. However, there are

some internal settings that you may have to modify. See the comments in the script for details. Here's an example, running

from the Windows command-line (Linux would be similar). First, I need to be in the working directory I where I unpacked

the zip archive:

I must have compiled my code, so that the necessary .class files are in the src directory tree. Working in Eclipse, that

would be the bin directory tree.

Read the comments in gradeJ3.py; you may need to comment out some lines and uncomment others, depending on

whether you are working with Eclipse, and whether you are working on Windows or Linux/macOS.

Run the script with Python:

The script will:

run prQuadGenerator.jar to create the reference data

move the seed file into the src (or bin) subdirectory

run testDriver to produce your output

writes messages as it processes the comparisons between the reference output and your output

Watch for error messages from the script; fix and repeat. If all goes well, the script will produce a comparison file for each of

the test output files:

Examine each of these to see how you did; fix and repeat as necessary.

Z:\J3\working > dir

09/18/2020 08:17 PM 3,093 gradeJ3.py

08/22/2020 05:01 PM 5,262 LogComparator.jar


09/21/2020 10:14 PM src

09/18/2020 11:50 AM supplied

Z:\J3\working > dir comp*.txt

09/21/2020 10:25 PM 45,891 compTestInsertion.txt

09/21/2020 10:25 PM 5,204 compTestRegionSearch.txt

09/21/2020 10:25 PM 466 compTestTreeInitialization.txt

Z:\J3\working > python gradeJ3.py

. . .

java -jar LogComparator.jar 1 refTestTreeInitialization.txt

./src/TestTreeInitialization.txt > compTestTreeInitialization.txt

java -jar LogComparator.jar 2 refTestInsertion.txt ./src/TestInsertion.txt >

compTestInsertion.txt

java -jar LogComparator.jar 3 refTestRegionSearch.txt ./src/TestRegionSearch.txt >

compTestRegionSearch.txt



What to turn in and how

This assignment will be auto-graded under CentOS (which should not matter at all) using Java version 1.8 or later, and the

posted testing/grading code.

You should document your implementation in accordance with the Programming Standards page on the course website. It is

possible that your implementation will be evaluated, by one of the TAs, for documentation and design, as well as for

correctness of results.

Submit your prQuadTree.java file (not a zip or jar) containing your PR quadtree generic to the Curator System. Submit

nothing else. Grading will use a reference implementation of the Point class, in order to avoid problems. Your solution

should not write anything to standard output.

Your submitted source file will be placed in the appropriate subdirectory with the packaged test code, and will then be

evaluated by running the supplied testing script. We will make no accommodations for submissions that do not work with

that script.

Warning: the requirement here is for a plain, uncompressed Java source file. We will not accept files in any other format

(e.g., tar files, 7-zip'd files, gzip'd files, jar files, rar files, …). Such submissions will NOT work with the supplied script, and

will be discarded when we run the grading code ourselves.

You will be allowed to submit your solution multiple times, in order to make corrections. Your score will be determined by

testing your last submission. The Curator will not be used to grade your submissions in real time, but you will have already

done the grading using the posted code.

Instructions, and the appropriate link, for submitting to the Curator are given in the Student Guide at the Curator website:

http://www.cs.vt.edu/curator/.

Design and implementation requirements

There are some explicit requirements, in addition to those on the Programming Standards page of the course website:

You must implement the PR quadtree to conform to the specification.

The insertion logic must not allow duplicate (according to equals()) records to be inserted. Think about what

could happen if you did not prevent this.

The insertion logic must not allow the insertion of records that lie outside the world boundaries.

Under no circumstances should any of the PR quadtree member functions write output, except for a display()

method and its helper, if you choose to implement that (the test harness will never call such a method).

When carrying out a region search, you must determine whether the search region overlaps with the region

corresponding to a subtree node before descending into that subtree. The Java libraries include a Rectangle class

which could be (too) useful. You may not make use of the Rectangle class from the Java library, but it is

acceptable to make use of those methods during development of a solution to this assignment.

When carrying out a region search, the order in which you add elements to the vector does not matter, since the testing code will sort the elements before considering them.

Naturally, your implementation of region search should be efficient; therefore, it must not look at subtrees that could not possibly contain elements that fall in to the specified region. This will be checked by the course TAs.

http://www.cs.vt.edu/curator/



Pledge

Each of your program submissions must be pledged to conform to the Honor Code requirements for this course. Specifically,

you must include the following pledge statement at the beginning of the file that contains main():

// On my honor:

//

// - I have not discussed the Java language code in my program with

// anyone other than my instructor or the teaching assistants

// assigned to this course.

//

// - I have not used Java language code obtained from another student,

// or any other unauthorized source, including the Internet, either

// modified or unmodified.

//

// - If any Java language code or documentation used in my program

// was obtained from another source, such as a text book or course

// notes, that has been clearly noted with a proper citation in

// the comments of my program.

//

// - I have not designed this program in such a way as to defeat or

// interfere with the normal operation of the grading code.

//

//

We reserve the option of assigning a score of zero to any submission that is undocumented or

does not contain this statement.

Change Log Version Date Change(s) 6.00 Oct 9 Base document

[1] When specifying the classpath, the separator must be a semicolon (';') on Windows and a colon (':') on Linux. On

the other hand, when specifying the classpath, you may use either the backslash ('\') or the forward slash ('/') on

both Windows and Linux.

But, when specifying actual paths, as in the path to a file, you must use the appropriate path separator ('\') on

Windows, but ('/') on Linux.

PR Quadtree Project for CS 3114 · 2020. 10. 12. · CS 3114 Data Structures and Algorithms Project...

Documents

Transcript of PR Quadtree Project for CS 3114 · 2020. 10. 12. · CS 3114 Data Structures and Algorithms Project...