CISC181 lab04a, Fall 2005
(section 010-012, Instructor: P. Conrad)

Introduction

This lab is an introduction to project 1a, the drawingMaker project.

The main purpose of this lab is to get you ready to do project 1a. In fact, when you finish this lab, you'll be already part of the way done with project 1a.

You should choose which version of project1 you want to do before you start this lab!!!

There are two alternatives for project 1:

Before starting this lab, you should look over the descriptions of both projects and decide which one you want to complete.

• If you plan to complete proj1a, the drawingMaker, you should not do this lab. You should do this lab, lab04a.
• If you plan to complete proj1b, the wavMaker, you should do the other lab, lab04b.

Completing one or the the other does not "lock you in"; you are permitted to change your mind, and you are permitted to "mix and match".

But if you change your mind, or "mix and match", you'll end up doing more work, and not getting any extra credit. Once you've completed either lab4a or lab4b, you are half-way done with the corresponding project. Switching horses in mid-stream will cause you to have to start over from square one, and not earn you any extra credit. So, choose wisely.

Learning objectives common to both projects:

By the time you finish either verson (lab04a + proj1a, or lab04b + proj1b), you'll have demonstrated your ability to:

1. Write data to the screen using cout, and to external files using ofstream objects.
2. Modify existing function and create new functions that use parameters of type int and double (passed by value), and call these functions where appropriate.
3. Modify and create functions that pass parameters of type ostream (by reference).
4. Use for loops, nested for loops and if/else.
5. Use Makefiles and separate compilation to manage a project that is moderately complex in size.
6. Make files available on the web.

Learning objectives present only on lab04a/proj1a (drawingMaker)

If you choose lab04a + proj1a, the drawingMaker project, you'll also acquire the following skills.

1. Using gnuplot to create graphics.
2. Controlling the creation of gnuplot files and data file for gnuplot from a C++ program.
3. Basic principles of working with 2D graphics (e.g. using sine and cosine to determine x, y coordinates, and scaling and translating figures in a cartesian plane.)

Folks with some background (or interest in) drawing and visual art may find this project particularly interesting, but it is not necessary to have that background to be successful.

Learning objectives present only on lab04a/proj1a (wavMaker)

If you choose lab04a + proj1a, the wavMaker project, you'll also acquire the following skills:

1. The difference between big-endian and little-endian byte orderings
2. Working with sample size and bit rate in digital audio
3. Generating simple sounds by the use of sine waves
4. Concepts of frequency and amplitude, and their relation to musical concepts of pitch and volume.
5. Use of the memcpy function with (void *) pointers.

Folks with a background (or interest in) music may find project1b particularly interesting, but it is not necessary to have that background to be successful.

Step-by-Step Instructions

Step 0: Generating a pentagon and a five pointed star.

In a previous lab, you have seen how to use gnuplot to plot points that you entered by hand using emacs or vi to create a data file (e.g. initials.dat).

Now, you will write two programs, lab04pent.cc and lab04star.cc. lab04pent.cc will draw a pentagon, while lab04star.cc will draw a five pointed star.

Both the pentagon and the star will be contained within a circle centered at the origin, with a radius of r units. (Prompt the user to enter a value for r at the beginning of the main function). You won't be drawing that circle of radius r, but you will be using that circle as a "reference" for plotting the points.

In both cases, you need to locate five points on the x,y plane. The first point will be at (0,r). On the unit circle (remember trigonmetry?) this point is at 90 degrees (or /2 radians). The other four points will be at angles of 360/5 degrees around the circle from this point (or 2/5).. You can use trigonmetry to determine the x,y coordinates of these points (sin(), cos(), etc.... .remember SOHCAHTOA?). Consult your Deitel/Deitel text on details of using #include <cmath> to access the sin() and cos() functions (remembering to use radians rather than degrees).

In both lab04pent.cc and lab04star.cc, you'll open an external file inside the C++ program (with ofstream). For lab04pent.cc, call this file "pentagon.dat". Write out the five points to this file, in order, and then write the first point at the end again (to close up the pentagon). Then, close the pentagon.dat file, and open another external file (you'll need a second ofstream object) called "pentagon.gnuplot". Use the A.gnuplot and CIS.gnuplot from lab03 as a model. Write out the contents of pentagon.gnuplot using C++ stream insertion operators. Set the xrange and yrange appropriately so that the entire pentagon is visible in the output file.

Then, create a shell script file penatgon.sh, similar to the following:

#!/bin/sh
#pentagon.sh (your name here, date here, section number here)


TARGET=$HOME/public_html/cisc181/lab04



gnuplot pentagon.gnuplot
mkdir -m 755 -p $TARGET

cp pentagon.png $TARGET
chmod -R 755 $TARGET

After you create this script (with a text editor), use this command to make it executable:

chmod u+x pentagon.sh

For lab04star.cc, you'll be writing out the points in a way that draws a star. Call your output file "star.dat". Define two functions called:

double xStarPoint(int pointNum, double radius);
double yStarPoint(int pointNum, double radius);

The function xStarPoint() will take a point number on the star (where point 0 is the first point, point 1, is the second point, etc. through point 4) and the radius of a circle, and then calculate a point on that circle (using trig functions). The function yStarPoint() does the same thing for the y coordinate.

(Note that when we write "xStarPoint()" with the empty set of parentheses as part of standard english text, this is a convention understood among C, C++ and Java programmers as a way of indicating in text that "xStarPoint" is the name of a function. It doesn't mean that xStarPoint() it is a function that takes no parameters. If we wrote "xStarPoint();" with an empty set of parentheses and a semicolon after it in a program, however, as a function call, that would mean that xStarPoint() takes no parameters.)

For the star, you need to connect point 0 to point 2, point 1 to point 3, point 2 to point 4, etc., all the way around the circle. You may find that the % operator is useful for doing this in a loop (mod, or "remainder after division").

You should write the program in such a way that the number of points in the star can be changed by only changing a #define, or a constant.

When you have finished writing the points, close the output file. Then, n generate the gnuplot script (star.gnuplot) by also opening as an output file, and writing it out with stream insertion operations. Set the xrange and yrange appropriately, e.g. if the radius r is 10, use [-10,+10] or [-11,+11] so that the entire star appears in the output.

What to turn in:

• You'll make only one script file, lab04s0.txt that covers both the lab04pent.cc and lab4bc.cc programs.
  In the script file lab04s0.txt, do the following steps:
  1. cat your lab04pent.cc file
  2. compile your lab04pent.cc file, but don't run it yet
  3. do an rm command that gets rid of any leftover "pentagon.dat", "pentagon.gnuplot", and/or "pentagon.png" files from previous steps, and then do an ls command
  4. run your lab04pent executable
  5. cat your pentagon.dat, pentagon.gnuplot, and pentagon.sh files
  6. run your pentagon.sh shell script
  7. do an ls command to show that pentagon.dat, pentagon.gnuplot and pentagon.png now exist.
  8. repeat steps 1-7 for your lab04star.cc file (substituting "star.dat", "star.gnuplot", "star.png" and "star.sh" as needed)
• Make sure that your pentagon and star files are readable on the web at the URL http://copland.udel.edu/~userid/cisc181/lab04
  Your TA will check this by going to the web after you turn in your submission.

Submission Instructions

For Step 0:

• Upload these files to WebCT and submit:
  • lab04pent.cc, lab04star.cc, lab04s0.txt
• Print your lab04s0.txt file
• Important: before turning your printout in to your TA, get a highlighter, and find the spot where you do the ls commands before and after running lab04pent, and lab04star. With the highlighter, circle the entire output of the ls command "before". Then highlight the command where you run the executable program (e.g. ./lab04pent or ./lab04star). Finally, find the new files that get created by your program and by your shell script (the ones that did not exist in the "before" output), and highlight each name. For example, for lab04pent, the files you highlight should be pentagon.dat, pentagon.gnuplot and pentaon.png.
• Be sure that http://udel.edu/~userid/cisc181/lab04 (where userid is your userid) is readable and contains your pentagon.png and star.png files (which should also be readable).

Step 1: Preview the finished project for project 1

Go to the web page http://udel.edu/~pconrad/cisc181/05F/pngFiles/proj1 and look at the .png files you see there. Each is a picture that you will draw as part of project 1. You'll draw these pictures by making some changes to a C++ library stored in a pair of files called drawings.cpp/drawings.h, and then writing some C++ programs that utilize this library.

In each case, you'll draw a picture that looks just like the one shown—with one exception: the file called drawPhillsPicture.png will be called drawXXXXsPicture.png in your directory, where XXXX is your own first name. The figure drawXXXXsPicture.png will be different from mine; it will be an expression of your own creativity. You'll read more about that when you look at the instructions for project1. For now, I just wanted you to start by looking at these files; lab04a is a warm-up for project 1a, and I wanted you to have an idea of where this lab is headed.

Step 2: Now preview the finished product for this lab and understand what you need to do

Now look at the files in each of two web links below. They show a set of .png files produced by the code that you can copy from the lab04a subdirectory on the course web page (under the labs link.) The "before" pictures show the .png files that are produced when you run the programs as they are right now. The "after" pictures show what the png files should look like after you are finished with some changes to the C++ code.

You should notice several differences. The following tables explains the differences, and where you will be making changes in the C++ code that result in the "after" pictures instead of the "before" pictures.

Notes on this table:

1. You'll add two lines and a star to make the Texas flag. The drawTexasFlag function has a comment that mentions a web site where you can get more detail on the exact proportions of all the elements of the flag. Note that for now, the star can be a simple five pointed star (it doesn't have to be the outline star as explained in lecture, and illustrated in the proj1 png file web page.) There is already a routine in the drawings.cpp file that you can use to draw this five pointed star.
    
   
2. The finished drawNightFlags.png file has 6 stars, but the starting point drawNightFlags.png contains only three. Your next job is to add some more calls to drawStar into the drawNightFlags.cpp file so that there are at least six stars in the sky.
   
   
   You can rearrange the stars, or change their values (size, number of points, position, skip value, etc.) to make them look nice. They don't have to match mine exactly—in fact, it would probably be nicer if they didn't. You just need six stars scattered in the sky somehow. Use your imagination.
   


3. Your last job is to add a new function to draw a french flag, and a call to that function inside drawNightFlags.cpp. That will add the French flag to the drawNightFlags.png file. You'll need to add a drawFrenchFlag prototype inside the drawings.h file, and a function definition inside drawings.cpp, and then a call to that function inside drawNightFlags.cpp.
    
   This should re-enforce a key concept you need to be sure you have at this point in the course: the difference between and among function prototype, definition, and call. 
   
   

Note that this step is just "understanding what you are supposed to do". Before you actually dive in, look over steps 3 and 4.

Step 3: Understanding the Makefile in this directory

The Makefile in this directory has several rules in it that will help you complete the project efficiently.

First, try typing "make all".

This will compile all the routines, and then run shell scripts that create each of the .png files.

Then, try typing "make install". That will create your ~/public_html/cisc181/lab04 directory, and copy all your .png files into that web directory, and set the permissions correctly.

Look at the contents of the Makefile, and try to understand the "make install" rule. The -p flag on the mkdir command makes sure that in case the directory already exists, no error message is created. the "-m 755" option builds a "chmod" for the directory into the mkdir command. Make sure you are familar with both of those Unix commands for the next exam (ask your TA and/or your instructor for help if you are not sure.)

You won't need to modify the Makefile for this lab. However, you'll need to modify it for project 1, so try to understand all the steps in the Makefile and what they do. Ask your TA for help during lab, and your instructor for help during lecture if you have questions. Your Anderson textbook also has information about Makefiles.

Step 4: Now, make the necessary changes to the C++ files

Make the changes in drawings.h, drawings.cpp, drawNightFlags.cpp.

Use the "make clean", "make all", and "make install" commands as needed to see the necessary changes take place in the .png files. You can use a web browser to check the contents of those files as you work.

Note that you can just type "make" instead of "make all".

A side note: note that in the drawings.cpp file, I used "#include <iomanip>", "using std::setiosflags" and "setiosflags(ios::fixed)". This is apparently what you have to do to get around the problem that some older version of g++ don't support the "fixed" keyword properly.

Once you have finished this, and all of your drawings look right, and your code is ready to turn in, you have two more things to do for this lab: update some links on your web page, and create a "tar file" to submit. The remaining steps in this lab will walk you through all of that.

Step 5: Some background on HTML that you need before you continue.

You'll be adding a "link" to your lab04 directory on your web page. This section explains how to do that.

Note: Even if you already know a lot about HTML, read this section. It contains terminology that might be on the next two exams.

First, as background, let's clarify the difference between your personal web page, which is controlled by the file ~/public_html/index.html, and your CISC181 web page, which is controlled by the file ~/public_html/cisc181/index.html. If I direct you to add something to your CISC181 web page, you should use emacs (or vi) to change the file ~/public_html/cisc181/index.html.

Next, let's understand how to "add a link" to a web page. Up until now, you've added links by following examples. Here's the "theory" behind adding a link.

In HTML (the language used to describe web pages), an "element" is anything in the following form:

<foo> ... </foo>

In this case, foo is the name of the element. The element is tagged with a start tag such as <foo>, and a close tag such as </foo>. The name of the tag is surrounded in with the less than (<) and greater than (>) signs, i.e. < >. These symbols are often called "angle brackets" in this context, since they are not being used to signify less than or greater than.

Some elements are defined with tags that contain attributes. An attribute is listed as part of the opening tag. For example, to make the words my lab04 files link to the directory ~/public_html/cisc181/lab04, one would include the following text in the HTML file:

Note that the <a> open tag includes the text href="http://udel.edu/~userid/cisc181/lab04". This is called the href attribute of the <a> tag (a stands for anchor). The href attribute lists the URL of the target of a link. The </a> close tag show where the link ends. This form of link is called an "absolute" link becaues it links directly to a specific absolute location. You could move this HTML code to any location on the web and it would still point to the same place.

Another way to specify this link is with a so-called "relative" URL. The relative URL is shorter to type because it relies on the fact that you know something about where the HTML file is located. For example, suppose you know that your HTML code is stored in the following file on strauss: ~/public_html/cisc181/index.html. In that case, you can specify a link to the files in ~/public_html/cisc181/lab04 with the following HTML code:

Note that the "dot slash" (.) refers to the "current directory", just like it does in Unix commands. So, ./lab04 refers to the lab04 subdirectory of the current working directory, i.e. the one where this index.html files is located, i.e. ~/public_html/cisc181. This way of specifying the directory is shorter, and it can also be more efficient. An key difference with this technique is that if the HTML file is moved, the link it contains doesn't point to the same place anymore; it will point to the ./lab04 subdirectory of whatever directory that html file is moved to. (So, that's one more thing you need to know for your next exam: the difference between an "absolute" link and an "relative" link.)

You can (and should) read more about this in your Deitel/Deitel textbook in Appendix E; the section on linking is on pages 1242-1245.

Step 6: Link your CISC181 web page to your lab04 files.

In this step, you will add a link to on your CISC181 web page that helps your TA find your lab04 files. By this point in the lab, the subdirectory ~/public_html/cisc181/lab04 should already exist, it should contain your two .png files, and those files should be readable on the web.

So now, make a link to that directory (which is accessible by the URL http://udel.edu/~userid/cisc181/lab04) on your CISC181 web page.

As a reminder, your CISC181 web page is the file ~/public_html/cisc181/index.html, and is referred to by the URL http://udel.edu/~userid/cisc181.

Step 7: There is no step 7

Step 8: Creating a tar file of your finished product.

Don't start this step until you have finished all your programming, and are ready to submit your work. However, don't wait until this last minute; you may need some time to figure this part out.

A "tar" file is a file that allows an entire collection of files to wrapped up into a single file.

You may be familiar with "zip" files, which are often used to distribute software packages on Windows PCs, or "sit" files which are used to distribute files on Macintosh computers. The files known as "tar" files are similar.

(A bit of history: "tar" originally stood for "tape archive". It's still the format sometimes used to store backup files on tape drives.)

To create a tar file from your lab04 files, follow these steps:

1. Change into your ~/cisc181/lab04 directory and do a "make clean". This is very important! If you don't do this step first, you'll end up with a tar file that will be huge; this will annoy your TAs greatly and cause your final grade to be lowered.
   
2. Change directory to one directory above your ~/cisc181/lab04 directory. You can you can use "cd .." to move up one level from your current directory, or you can use "cd ~/cisc181" to go there directly.
   
3. Use the command:
   

     tar -cvf lab04.tar lab04

   This command says "create a new tar file named lab04.tar"
   (that's the -cvf lab04.tar part) and put all the files from the subdirectory lab04 into it.
   
4. To test your file, create a new subdirectory called ~/cisc181/test, and cd into it.
   Copy your lab04.tar file into that directory. Then use the command:
   

     tar -xvf lab04.tar

   This command should expand the lab04.tar file, and leave you with a new subdirectory ~/cisc181/test/lab04 that contains all of the files from your lab04 directory. Change your working directory into that directory and use the "ls" command to list your files. Then, try the "make clean", "make all" and "make install" commands and make sure that everything still works properly. If so, then you can now submit "lab04.tar" as your submission to WebCT.
   
   Note: you have reached a milestone in your development as a Unix programmer: you have created your first "package". A package is a tar file that contains source code, and a Makefile. Sometimes these packages are called "tarballs", and they are how professional Unix programmers distribute their software.
   

Finishing up and Submitting

For Step 0:

• Upload these files to WebCT and submit:
  • lab04pent.cc, lab04star.cc, lab04s0.txt
• Print your lab04s0.txt file
• Important: before turning your printout in to your TA, get a highlighter, and find the spot where you do the ls commands before and after running lab04pent, and lab04star. With the highlighter, circle the entire output of the ls command "before". Then highlight the command where you run the executable program (e.g. ./lab04pent or ./lab04star). Finally, find the new files that get created by your program and by your shell script (the ones that did not exist in the "before" output), and highlight each name. For example, for lab04pent, the files you highlight should be pentagon.dat, pentagon.gnuplot and pentaon.png.
• Be sure that http://udel.edu/~userid/cisc181/lab04 (where userid is your userid) is readable and contains your pentagon.png and star.png files (which should also be readable).

For Steps 1-8

1. Make a script called lab04.txt. In your script, you should cd into your lab04 directory, cat all of your .cpp files and your .h file, and then cat your Makefile. Finally, do following three commands: "make clean", "make all", and "make install". That completes your script.
2. Then, submit your lab04.txt and your lab04.tar file to WebCT. Be sure that your lab04 tar file was created right after doing a "make clean". If you create it correctly, the size should be no more than a couple hundred KB, maybe less. (You can use the unix command ls -lh to see how large each file is in bytes, KB, MB, or GB.)
3. Print your lab04.txt file and give it to your TA.
4. Make sure you have a link on your CISC181 web page to your ~/public_html/cisc181/lab04 directory.

Grading: 130 points total

Next Steps

• Now you are ready to start on Project 1.

You will find the description of Project 1 in the project directory of the course web site.