Programming assignment #1 - Paint program

CS 248 - Introduction to Computer Graphics
Spring Quarter, 1995
Marc Levoy
Handout #4

Demos on Monday, April 24

Writeups due on Tuesday, April 25 by 5:00pm

Your assignment is to write a 24-bit paint program that runs on the Sweet Hall SGI workstations. You will use your program to prepare texture maps for the shader in assignment #4.

Required functionality

1. Overpainting brush. Implement a simple rectangular overpainting brush as described in handout #6. (available April 13). 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 #6. 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. Think carefully about interpolating hue (H), given the circularity of that axis. Weight should fall off smoothly to zero with increasing distance from the brush center. Allow slider control over one or more parameters of the weighting function. Try to give your brush a natural feel.

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 a smooth surface for the sake of the visualization.

Support software

To eliminate X or GL hacking, teaching assistant Apostolos (Toli) Lerios has written a software package that displays any number of windows, henceforth called canvases, and 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 handles all mouse events and cursor display outside the canvas. You handle mouse events inside the canvas. In particular, you are responsible for displaying a software cursor in the canvas as shown in class. Use any shape and coloration you like. Your cursor should be clearly visible over any image, but it should avoid obscuring too much of the area being painted. Implement clipping of the software cursor and brush action to the boundaries of the canvas to allow unimpeded painting of pixels near the boundary even if the brush straddles the boundary. 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.

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. Depending on the sort of tinting you implement, you might wish to continue painting at full throttle even if the mouse is held motionless, or you might wish to apply a new brush instance only if the mouse moves some minimum distance. Experiment with different effects. 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.

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/xsupport/README. Everything you need to know is contained in this file. 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.

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. See Toli's documentation for details. Use radio buttons to switch between modes. For more help with your debugging, we suggest using the "supersnoop" (for SGIs) or "xmag" (for Sparcs and Decstations) standalone pixel magnification utilities. If you want a test background image, large and small versions of an alpine pasture are available. To get an intuition for how RGB and HSV color mixing work, play with the SGI "cedit" utility. Use the right mouse button to switch modes. See /usr/class/cs248/bin/README for details on where to find supersnoop and xmag. The alpine pasture is in /usr/class/cs248/data/textures.

Submission requirements

Signup sheets will be posted in the Sweet Hall lab a few days before Monday, April 24. Each team will sign up for a 1-hour slot on Monday sometime during which they will be called upon to give a 15-minute demo. All demos must be given in the lab. By 5:00pm on Tuesday, April 25, you must submit an on-line commented copy of your source code and a brief (1-2 pages) hardcopy description of the functionality implemented. See /usr/class/cs248/submissions/README for instructions on submitting your code on-line. Bins for turning in and retrieving the hardcopy description of your functionality are located near Sarah's office. The assignment will be graded on correctness (40 points), efficiency (20 points), programming style (20 points), and the elegance of your user interface (20 points).

Working in teams

You may work alone or in teams of two. For a team effort, you must implement two of the following bells and whistles. Alternatives are acceptable if approved in advance. If you have completed the assignment and wish to earn extra credit, you may add more bells and whistles.

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

2. Implement 24-bit versions of three or more fancy brushes from Alvy Ray Smith's tutorial (handout #5). Examples are cycle paint, z picture paint, filter paint, or smear paint.

3. Implement painting on textured paper. Provide some kind of user control over the texture. For inspiration, look at Fractal Painter.

4. Implement cloning such as found in Fractal 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).

5. Implement a fill algorithm from section 19.5 of the textbook. For a second bell, implement a soft-filling algorithm.

6. Implement unlimited undo. Most commercial painting programs allow "undo" of a single brush stroke (from button down to button up). An artist working rapidly may lay down several brush strokes before realizing that a mistake has been made. Single-stroke undo is therefore seldom sufficent. Hence the need for unlimited undo. Some cleverness will be required to avoid excessive memory use.

7. 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).

8. Implement colormap quantization combined with Floyd and Steinberg error diffusion dither as described in the textbook.

9. Implement Paul Heckbert's median-cut colormap quantization algorithm as outlined on page 600 of the textbook. We'll supply you with the full paper if you're interested in implementing this. You probably won't have much luck, however, painting in the resulting non-uniformly quantized colorspace. For extra credit, use a perceptually based color metric.

10. 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.

For the error diffusion dithering and colormap quantization bells, you'll need to display a colormapped image. Toli's package does not give you access to the colormap, but you can easily simulate one on the SGI workstations by displaying appropriately quantized 24-bit values. This scheme won't work on an 8-bit workstation, where Toli's dithering will interfere with your simulated colormapping or dithering.