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 RGB color mode (not grayscale, etc.). The mode of an image can be set in the menu item Image>Mode. 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.

Common Problems

Sometimes having spaces in the names of images can cause problems. To avoid this use snake_case or cameCase for your file names.

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.

color-swatch-table_sam-ballardini.jpg --- an example pallette created by a CS137 student.

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. Also, the slides must be square (equal width and height) and have dimensions that are powers of 2 (64, 128, 256, 512, 1024, 2048, or 4096).

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. Make sure the color mode is not grayscale.

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, follow these steps:

• Prepare the slide (and optional mask) in your program of choice
• Rename the file as described above
• Copy the images to a USB key
• Insert the USB key into the Windows kiosk machine (the port is on the left side)
• Swipe kiosk screen left to right until the Windows taskbar is visible on the bottom
• Open the Windows File Browser from the taskbar
• Navigate to your USB key on the left panel of the File Browser
• Copy the image data you wish to transfer
• Navigate to the "share" link on the left panel of the File Browser
• Navigate to your home directory at cs137\students\${your_username}
• Paste your image files to your home directory
• Eject your USB key
• Start or restart Cavepainting
• Tap the VRG3D window to give it focus
• Enjoy your data!

Using Images

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