Import images into CavePainting

You can add custom color palettes, slides, paint stroke patterns, or paint stroke masks to CavePainting simply by loading image files into the program. In order to work, though, they need to be in a particular size and format, and have a particular sort of name. Loading them into the program is pretty easy, but the first time you do it you need to perform an extra setup step.

Image Format

All images used in CavePainting must be JPEGs (extension .jpg). In the filename patterns described below, an asterisk (*) indicates any text you want. The program loads all your images on startup, so if CavePainting fails to start properly, new images that you're loading for the first time may be to blame. Check the Troubleshoot CavePainting startup crashes HOWTO for instructions on fixing your images.

Color Palettes

Custom color palettes must be 512x512 JPEGs with a filename of the form color-swatch-table*.jpg.

color-swatch-table_example.jpg — one of the default CavePainting color palettes.

Slides

Slides, also known as "billboards", are flat images that you can place in virtual space like floating pieces of paper. Each slide depends on two files, a picture and a mask, which must be the same size and have matching filename patterns.

File	Name Pattern	Size	Function
Picture	slide*.jpg	64x64, 128x128, 256x256, 512x512, 1024x1024, 2048x2048, 4096x4096	The picture on the slide.
Mask	alphamask*.jpg		A black-and-white image matching the picture. The picture is visible where the mask is white, and it's transparent where the mask is black.

slide_example.jpg

alphamask_example.jpg

Strokes

You can customize the appearance of paint strokes in two different ways. You can put a particular picture, or pattern, on the stroke, or you can make it transparent in a particular shape with a mask.

Palettes of patterns or masks each have 16 entries in them, each of which is a 64x64 image. In order to tell CavePainting what all 16 images are, you import them all in one file, with the square images concatenated together in a row. This gives you 16 64x64 squares lined up in a row, resulting in a 1024x64 JPEG file that you import into the program. See the examples below to get a better idea of what this means.

The vertical direction in the pattern or mask image is aligned with the direction of the stroke — that is, a pattern that looks like horizontal stripes will result in a brush stroke with stripes across it, whereas a pattern of vertical stripes will result in a brush stroke with stripes along its length.

Stroke Patterns

A stroke pattern applies a pattern of color to a brush stroke. You should make sure that each element of any custom stroke pattern palette that you create has a little bit of visual texture to it, rather than having any large, flat areas of color. Depth perception of virtual objects in the Cave requires that your eyes can match up their two views of every object. If an object has no surface texture, it is much harder to match up than one with a little bit of texture to it.

The filename format for stroke pattern palettes is pattern*.jpg.

patterns_example.jpg — the default CavePainting stroke pattern palette.

Stroke Masks

A stroke mask applies a pattern of transparency to a brush stroke. Stroke masks are black-and-white images; where the mask is white, the stroke is visible, and where it is black, the stroke is transparent. You probably want any custom stroke mask palette that you create to have one all-white 64x64 block in it, so that you always have the option of drawing an entirely solid stroke.

The filename format for stroke mask palettes is brushtips*.jpg.

brushtips_example.jpg — the default CavePainting stroke mask palette.

brushtips_dithered.jpg — a stroke mask palette for dithered translucency.

Loading Images

To import images into CavePainting, log into any of the black computers in the Cave room. They are named dev1 through dev4.

Setup

You have to do a little bit of setup the first time you import images. After that, you should be able to just follow the steps in the next section.

1. Right-click on the desktop and select "Open Terminal".
2. In the window that opens, type

   /share/cs137/cs137-init

   and hit enter.
3. Close the window.

This step creates a folder on your desktop called "CavePainting Directory". This is where all your files go. If you ever don't see this directory, just repeat the steps above.

Transferring Files

To load files into CavePainting, you need to get them onto one of the black computers in the Cave. You can do this by plugging a keydrive into the front of the computer, emailing files to yourself, uploading files to some server, or any other way you choose. Whatever you do, download the files to your desktop, and then drag-and-drop them into the folder called "CavePainting Directory" that you see on the desktop.

Before you leave the Cave, be sure you quit properly:

• If you used a USB keydrive, right-click on its icon and select "Remove Hardware" or "Safely Remove" or "Unmount". If you just unplug the keydrive, you might corrupt the data on it and confuse the computer.
• Log out of the computer so nobody else can use your account.

That's it! The next time you open up CavePainting, your new images should be enabled. If you don't see them in the palette where you expect them, try pushing the button on the non-brush controller to switch palettes.

Using Images

For instructions on how to use slides, stroke patterns, or stroke masks, see the Use Cavepainting HOWTO.