README
1There's a version of this document with pictures at
2<vamos.sourceforge.net/caelum>
3
4Usage: caelum [options] image-file.ppm
5 Run Caelum, a tool for creating sky boxes.
6
7The image file is mapped onto a sphere and six views are shown. The
8views are from the center of the sphere looking up (top row), down
9(bottom row), front, right, back, and left (middle row). When these
10images are mapped to the faces of a cube and viewed from the center of
11the cube, the view in any direction is indistinguishable from the view
12from the center of the sphere. The images for the sky box are
13extracted by taking a screenshot.
14
15
16Installation
17------------
18
19To install, copy .libs/lt-caelum to /usr/local/bin/caelum.
20Caelum requires libvamos-geometry and libsigc++. If you install Vamos
21first, you should be ready to go.
22
23
24Options
25-------
26
27--divisions=DIV
28-d DIV
29 Specify the number of latitude divisions. The number of longitude
30 divisions is twice DIV. The default value is 16.
31
32--height=HEIGHT
33-h HEIGHT
34 Specify the height of the window in pixels. The height of each view
35 entire window will be HEIGHT/2. The default is 1.5 times the
36 height of the source image.
37
38--width=WIDTH
39-w WIDTH
40 Specify the width of the window in pixels. The width of each view
41 window will be WIDTH/4. The default is twice the width of the
42 source image.
43
44--help
45 Display a help message and exit successfully.
46
47--version
48 Display version information and exit successfully.
49
50
51Controls
52--------
53
54<Left>
55<Right>
56 Rotate the image about the vertical axis.
57
58<Up>
59<Down>
60 Shift the image vertically.
61
62<Page Up>
63<Page Down>
64 Scale the image vertically.
65
66
67Example
68-------
69
70Load the sky image from the textures directory.
71
72 ./caelum ../data/textures/sky.ppm
73
74This image comes from the Sky collection at
75<http://www.vb3d.com/Textures.html>. It is not (and doesn't claim to
76be) a true panorama. As a result, the top is pinched in the center.
77Using the <Up>, <Down>, <Page Up>, and <Page Down> keys you can change
78the position of the horizon and make the mountains appear taller or
79shorter.
80
81When you're satisfied, take a screenshot and chop it up with
82an image manipulation program such as the GIMP. For Vamos, you need
83three images, the top view, the bottom view, and the entire strip of
84side views. The sky box images are specified in the XML track files.
85
86
87Possible Enhancements
88-------- ------------
89
90o The ability to write the transformed images to files would be
91 useful.
92
93o Better use of the blank space on the screen could be made by showing
94 instructions, current scaling parameters, or other useful bits of
95 information.
96
97
98Caelum comes with ABSOLUTELY NO WARRANTY. You may redistribute copies
99of Caelum under the terms of the GNU General Public License. For more
100information about these matters, see the file named COPYING.
101
102Report bugs to snick-a-doo@attbi.com
103