Programming assignment #1 - Paint program

CS 248 - Introduction to Computer Graphics
Autumn Quarter, 1999
Marc Levoy
Handout #3

Demos on Monday, October 11

Writeups due on Tuesday, October 12 by 5:00pm

Your assignment is to write a 24-bit paint program that runs on the Sweet Hall SGI workstations.

Required functionality

1. Overpainting brush. Implement a simple rectangular overpainting brush as described in handout #4. Allow slider control over the color and size of your brush. In this brush and in the tinting brush below, you are free to decide in which colorspace your color controls operate. For example, your sliders may control R, G, and B, or alternatively they may control H, S, and V.

2. Tinting brush. Implement a weighted mask-driven tinting brush as described in handout #4. Allow slider control over the color and size of your brush as described above. Regardless of which colorspace you employ for color control, you should perform your tinting calculations in HSV space (i.e. the single-hexcone space described in section 13.3.4 of the textbook). Using check boxes, allow the user to select which coordinate(s) are interpolated: H alone, S alone, V alone, H & S, H & V, S & V, or all three. Non-interpolated coordinates should remain unchanged. Think carefully about interpolating hue (H), given the circularity of that axis. Weight should fall off smoothly with increasing distance from the brush center, and should fall to zero at the edges of the brush. Allow slider control over one or more parameters of the weighting function.

3. Brush visualizations. Draw 1x (actual size) and 4x (enlarged by 4 in X and Y) visualizations of the current brush in a second canvas. These visualizations should depict the size, shape, and falloff of the brush. With some creativity, you can also depict the target R, G, and B, or alternatively the target H, S, and V. Update the visualization whenever a related slider is moved. The purpose of these visualizations is to understand the brush shape in its WYSIWYG, spatially discretized glory. Therefore, in the enlarged visualization, one pixel of the actual brush should be displayed as a 4x4 pixel constant-color block; don't interpolate for the sake of the visualization.

Support software

To eliminate X or GL hacking, we provide a software package, xsupport, that displays any number of windows, called canvases, a programmable number of sliders, and several kinds of buttons. You will need at least two canvases, one for your painting and one for your brush shape visualization. The size of these canvases is programmable. The support package runs on most X-compatible workstations. If you are working on a 24-bit workstation with hardware gamma correction (such as our SGIs), the package allows you to display your 24-bit painting directly. If you are working on an 8-bit color workstation with no hardware gamma correction, the package automatically dithers and gamma corrects your painting prior to display.

The package is described in the file /usr/class/cs248/support/src/xsupport/README.xsupport. Everything you need to know is contained in this file. We recommend you begin the assignment by copying the directory /usr/class/cs248/assignments/assignment1 to somewhere in your home directory structure and modifying the skeleton paint program provided. To use the package, you must program in C or C++. If you use an incompatible language or platform, you should write a software package that mimics our user interface as closely as possible as this will greatly facilitate grading. Remember that all demos must be given in the Sweet Hall SGI lab. To help us judge the performance of your program, it should be executing on a Sweet Hall SGI workstation as well as displaying there during your demo.

Some hints and additional requirements

• The support package handles all mouse events outside the canvas; you handle mouse events inside the canvas. Painting should start when the left mouse button is pushed and the mouse is in the canvas. It should stop when the button is released. While the button is pushed, you could either paint at full throttle even if the mouse is held motionless, or you could apply a new brush instance only if the mouse moves some minimum distance. Experiment with different effects. (You only need to implement one.) Note that the support package allows you to modify the rate at which you receive mouse events if the mouse is held motionless while the button is pushed.

• During painting, you should clip the brush action to the boundaries of the canvas. (This is required.) Your goal should be to allow unimpeded painting near the boundary even if the brush straddles the boundary. You want your painting surface to seem infinitely large, seen through a window equal to your canvas. If your clipping is working correctly, you should be able to paint the lower-leftmost pixel in your canvas using the upper-rightmost pixel in your brush even though most of the brush is beyond the canvas boundaries. Note that in keeping with the usual X convention, you retain control of the mouse when it wanders beyond the canvas boundaries as long as the button stays pressed.

• To facilitate debugging (and grading) of this and future assignments, allow the user to display the red, green, or blue components of your image in isolation by setting the appropriate mode flags on your canvases. (This is required.) See the support package documentation for details. Use radio buttons to switch between modes. For more help with your debugging, we suggest using standalone pixel magnification utilities "snoop" (at /usr/class/cs248/support/bin/iris4d/snoop or /usr/class/cs248/support/bin/iris4d/supersnoop) for SGIs, or "xmag" (at /usr/pubsw/X/bin/xmag) for Sparcs and other machines. If you want a test background image, large and small versions of an alpine pasture and other images are available at /usr/class/cs248/images/*.ppm. To get an intuition for how RGB and HSV color mixing work, play with the SGI "cedit" utility (/usr/sbin/cedit). Use the right mouse button to switch modes.

Submission requirements

Signup sheets will be posted in the Sweet Hall lab a few days before Monday, October 11. Sign up for a one-hour slot on Monday sometime during which you will be called upon to give a ten-minute demo. All demos must be given in the lab. By 5:00pm on Tuesday, October 12, you must submit an on-line commented copy of your source code and a README describing the functionality implemented. Be brief but complete; one screenful is enough. If you did something especially clever, tell us about it. To submit your code and README, simply change the current directory to your assignment1 directory and run the script "./submit" (which is also located at /usr/class/cs248/support/bin/sun4/submit).

The assignment will be graded on correctness (40 points), efficiency (20 points), programming style, including your writeup (20 points), and the elegance of your user interface (20 points). Note: the functionality, efficiency, and UI of your program will be graded based only on what you show us during the demo. Functionality you don't show us or that doesn't work will not be considered. Only your writeup and your code will be graded from your submission.

Extra credit

If you have completed the assignment you can earn extra credit by adding bells and whistles. Here are some suggestions. Feel free to make up your own.

1. Allow interactive manipulation of brush size, shape, and fall-off directly on the visualization displayed in the second canvas (as an alternative to sliders). Make your interface as intuitive as possible.

2. Implement a software cursor, used only when the mouse is inside the canvas, that more suitable for painting than the default arrow cursor. A good cursor would be visible over any image, regardless of color, and it would avoid obscuring too much of the area being painted. Segmentation faults are frowned upon, so remember to clip your cursor to the boundaries of the canvas. You can disable the hardware arrow cursor in xsupport by setting the "DisableHardwareCursor" member of the canvas structure to a non-zero value prior to calling LiftOff().

3. Implement some fancy brushes, such as a filter brush, smear brush, color cycle brush, or rubber-stamp brush with transparency. We'll describe these and others in the Friday help session for this assignment.

4. Implement painting on textured paper. Provide some kind of user control over the texture. For inspiration, look at MetaCreations's Painter program.

5. Implement cloning such as found in MetaCreations's Painter. A good paper on this technique is Paul Haeberli's `Paint By Numbers: Abstract Image Representations,' Computer Graphics (Proc. Siggraph), Vol. 24, No. 4, August, 1990, pp. 207-214.

6. Implement a fill algorithm from section 19.5 of the textbook. For more fun, implement a soft-filling algorithm.

7. Implement unlimited undo, allowing the user to "cancel" the effect of any number of brush strokes (from button down to button up). Why unlimited? An artist working rapidly may lay down many brush strokes before realizing that a mistake has been made. Single-stroke undo is seldom sufficient. Some cleverness will be required to avoid excessive memory use.

8. Record a painting session (multiple brushstrokes), then allow the user to change one or more brush parameters (color, size, shape, etc.), and "replay" the session, yielding a new painting. For extra fun, allow the user to control which brushstrokes are affected by a change. One way to select brushstrokes is to provide slider-controlled playback of the painting session (using your unlimited undo machinery). Another way would be geometrically, using a bounding rectangle or freeform lasso (like Photoshop).

9. Display in a third canvas the constant H, constant S, and constant V surfaces from a hexcone or other cylindrical colorspace. Allow selection of H, S, and V for your brush from this display. When a value is selected from one of the three surface, update the other two surfaces to display the appropriate slices from the hexcone. For extra credit, add an axonometric or perspective projection of the 3D colorspace showing in color the currently selected constant H, S, and V surfaces.