0: Introduction.

Most objects in Celestia, stars, planets, asteroids, etc, start out as
dull round globes. However, they can be given
complicated appearances by specifying image files to be wrapped
around them. These images, also called texture maps, can be used to
provide surface colors, a bump (shadow) map, a nighttime image,
cloud layers, a specular reflection map, and rings around the planet.

Despite the fancy name of "surface texture maps", these are all just pictures.
You can create them using a fractal planet generator,
your favorite paint program, or just copy them from a picture server.
Pictures do get
distorted when they are wrapped around an object in Celestia, but you
usually don't have to worry about that. If necessary, some tools
are available to provide the appropriate
counter-distortions in advance.

1.0: Texture Files.

1.1: Image File Types.

Celestia can make use of three different types of image files:
JPEG, PNG, and DDS texture format.

Discussion:

Each type of image has a
different primary advantage: size on disk, support for an
alpha channel (used for transparency or reflection), and performance,
respectively. In some cases, BMP files can be used as surface textures
for materials in 3DS models, but their use is discouraged.
(BMP is an extremely complicated standard. Celestia implements only a
very tiny fraction of it. If it works, you're lucky.)

Remember that the internal structure of JPG, PNG and DDS files are
quite different from one another. The file extension (the filetype)
is normally used by the computer to decide how
to interpret the file. Simply renaming a file from earth.dds
to earth.png will not work. Trying to interpret a DDS
texture as if it were a PNG image will certainly not do what you want.
Other operating systems may use a file's 16bit "magic number" to determine
the type of data that it contains. The "magic number" is contained in
the first two bytes of the file.

1.1.1: DDS Format.

DDS format is becoming popular with Celestia users who have current
generation graphcs cards.
The name is short for "Direct Draw
Surface", a standard first used in Microsoft's DirectX software. This format
can be used with most graphics chips that were designed within the past
few years. It does not work with some older graphics cards. As of v1.3.0,
there are three formats of DDS files often used with Celestia: DXT1,
DXT3 and DXT5. DXT1 is the smallest. It contains only a single highly
compressed picture. much like a JPEG image. DXT3 contains two somewhat
compressed texture maps:
the primary image and an Alpha channel. It's often used instead of a
PNG file. A DDS file created in DXT1C or DXT5 format can
contain multiple texture images. These "Mipmaps" in a DXT file are at
progressively lower resolutions and can be created automatically
by the NVDXT utility.
The graphics hardware will use the image which is at
the appropriate resolution for the size that the object is
being shown on the screen. This
results in better performance for objects that occupy fewer pixels.

DDS files can contain many other types of information that can be
used by graphics cards that support them. For example, in addition
to Mipmaps, DDS files have special provisions for
Cubicmaps
and
Normalmaps.

Standalone utilities and PhotoShop
plugins are available from ATI, NVidia and Microsoft
to convert various image formats into DDS files and to view DDS files as
thumbnail images. Some of these programs are mentioned on my
main Celestia Web page in section 9..

1.1.2: Wildcards.

Wildcard filetypes are available in Celestia v1.3.1 and later.
When a texture image is specified in an SSC flle or in the material
of a Mesh in any catalog file, you can use an asterisk (*) to tell
Celestia to use
whichever of four image file types that it finds.
Celestia will look for CTX, PNG, JPG and DDS files, in that order.
If you specify a texture
name of "Mars.*", for example, Celestia will look through the appropriate
texture directories for images named Mars.ctx, Mars.png, Mars.jpg and Mars.dds,
in that order. (See section 2.5 below for a
description of the CTX format, which is used for "Virtual Textures.")

1.1.3: Alpha Channel.

When a texture map image file contains an Alpha channel, Celestia
will do one of two things with the Alpha channel. If the texture is
specified using a Texture directive in an SSC or STC catalog,
that is, if it is being used as the surface texture of a planet or
model, its Alpha channel
defines the surface specularity: white areas are reflective, black
areas are dull. If the texture is used to define a cloud layer or
a planetary ring or is specified within a 3D model,
the Alpha channel defines the opacity of the surface: white is
completely opaque, black is completely transparent.

1.2: Image Colors.

Surface texture maps can be 24 bit color (8 bits each of Red, Green and
Blue). 8 bit greyscale images that are to be used as surface textures
must be converted to 24bit images.
Also, Alpha channels, which are used for specular highlights or
transparency, must be 8 bit grey-scale images. Although the
PNG image file format supports other color depths, Celestia can't use
those files. Developing a texture, height map or normal vector map
with greater color resolution and then reducing the resolution in the
final image usually
produces a better result than working in the lower resolution
required by Celestia.

1.3: File Sizes.

Celestia needs its image files to have dimensions (in pixels) which
are powers of two: 256x256,
1024x512, 4096x2048, etc.

Discussion:

The pixels are assumed to be square.
This size restriction is built into the
design of most graphics chipsets. Display packages that allow surface
textures with other
sizes actually have to rescale the images before they use them. It's
better to design your images at an appropriate size to begin with. This
provides better performance and
prevents loss of detail due to scaling. With Celestia, you have no
choice but to do this.

Celestia v1.5.0 (or later) makes possible the use of textures which are
not a power-of-two on a side. However, if the graphics card itself does
not support such a file size, Celestia will scale the image down
to a power-of-two size that it can use. This may severely damage
the quality of the texture.

1.4: File Locations.

Celestia looks for surface texture image files in a
textures subdirectory.
When loading its own objects, Celestia looks in its main directory.
When an Addon is being loaded, Celestia
first looks in the
textures subdirectory in that Addon's directory.
If the texture isn't found there, it will look in the main directory.

Within each textures directory.
Celestia looks in the subdirectories
medres,
hires,
and lores. Surface texture images specified in the materials
of 3D model Mesh
files must be in the medres subdirectory.

When you create an Addon (e.g. a planet orbiting some distant star)
its folder should be put in Celestia's "extras" folder. The Addon's
textures would go in folders within the Addon's folder.

On a computer running MacOS, Celestia's extras directory is likely to
be/Users/<userid>/Library/ApplicationSupport/CelestiaResources/extras/

As a result, on some computers running Windows 7, the Addon
(let's call it MyAddon) should be in the folder
C:\Users\<userid>\AppData\Local\Celestia\extras\MyAddon\Its textures would be in
C:\Users\<userid>\AppData\Local\Celestia\extras\MyAddon\textures\And its medres textures would be in
C:\Users\<userid>\AppData\Local\Celestia\extras\MyAddon\textures\medres\

2.0: Usage Within Celestia (How to use them).

2.1: Map Projections.

2.1.1: Simple Cylindrical.

Celestia's spheres require surface texture image maps that
have been created in simple cylindrical projection.

Discussion:

A Simple Cylindrical map projection is one of many ways
to describe the surface of a 3D sphere on a flat, 2D surface.

Surface textures to be used for spherical objects in Celestia
must be simple cylindrical projections
with 0 degrees of longitude in the center and 180 degrees of longitude
at the sides. The North pole should be at the top and the South pole at
the bottom of the picture.

Most maps of planets and moons that you find
on the Web are already in this format. Some maps have 180 degrees of
longitude in the center, however, and have to be edited so they'll
have consistant alignments when used with Celestia.

Within Celestia, Longitude is measured increasing toward the East,
toward the right side of the image. Often map references on the Web
will say something like "270 degrees of West Longitude." This is in the
opposite direction from what Celestia uses. 270 degrees West
is the same as 90 degrees East.

Background

When a flat image is wrapped around a sphere, it gets distorted and
stretched out of shape.

When used with Celestia,
rectangular images of planetary maps that are going to be wrapped
around spherical objects should be created in the format called
"Simple Cylindrical Projection", which is also known
as "Plate Carré" (spelled variously Caree, Carre & Carree).
This is one of many different
projection coordinate systems that have been developed so the surface
of a sphere can be mapped onto a flat surface. Simple Cylindrical
Projection is used by most 3D design systems when
wrapping a rectangular image around a spherical object.

Simple Cylindrical Projections have a distinctive appearance. The top
and bottom parts of the image are streatched horizontally.
The center of the image looks normal.
This stretching compensates for the fact that the top and bottem
are "squeezed" when they are wrapped around the poles of a sphere.
If you use an image that doesn't have this horizontal stretch,
the poles of a planet will look "pinched".

"Simple Cylindrical" or "Cylindrical Equidistant" = "Plate Carré"

"Plate Carré" in 3D

The more common Mercator projections, like the one below, look similar to
Simple Cylindrical Projections but have at least one major difference.
Latitude (north-south) dimensions on Mercator projections become
larger and larger as they approach the poles. The top and bottom of a
Mercator map
are stretched vertically while latitudes near the equator are shrunk.
In contrast, the latitude distances on Simple Cylindrical
Projections all have the same dimensions. They are not stretched vertically.

Mercator projection

When converting a piece of a flat map or picture into a surface map
for an imaginary planet, treating the initial image as if it were a
Mollweide projection seems to produce reasonable results. When it's
converted to Simple Cylindrical, the top and bottom get stretched
appropriately.

Mollweide projection

Whatever program you use to change an image's projection, you'll
probably
need to edit the cylindrical picture so that the features at its
sides match. Otherwise there'll be a
visible seam at the 180 degree position on the body drawn by Celestia.

Merged Cubic projection

2.1.3: Projection Software.

Various programs are available for remapping (distorting)
a "flat" image into a cylindrical projection.

Some freeware utilities are

A "Spherical Mapping Corrector" Photoshop plugin by
Richard Rosenman,

"Spherical Mapping Corrector" can be found at
http://www.richardrosenman.com/software/downloads/
It stretches the top
and bottom of an image horizontally more than the center of the image
so that the top and bottom don't create a "pinched" look at the poles.
The results are not necessarily mathematically accurate.

Photoshop plugins can be used with most paint programs, not just
with Adobe Photoshop.

Iris, by Christian Buil.

Iris is an astronomical image processing package
which includes functions to remap images among a dozen different map
projections. See
http://astrosurf.com/buil/us/iris/iris.htm.
Except for minor "off by one" bugs, Iris does use mathematically
correct conversions.

the "r" and "R" commands have been eliminated in Celestia
v1.6.0 and newer. Instead, use Celestia's menu Render / Texture
Resolution.

The resolution commands used in Celestia v1.5.1 and older are

r (reduce resolution)

R (increase resolution)

Discussion:

The Texture Resolution menu (previously "r" and "R" commands)
usually can be used to select among
Celestia's lower and higher resolution surface textures. (They work for
AltSurface textures, too.)

Celestia can select among as many as three different image resolutions
for the surface
texture of a body. The image files used for this must all have the same
name (e.g. earth.jpg), but they are kept in separate
subdirectories.

If an object's Texture declaration in an STC or SSC file
specifies a wildcard
filetype (e.g. earth.*), then the image files do not all
have to be the same type. Celestia will look for CTX, PNG, JPG and DDS
files, in that order. (See section 2.5 below for a
description of the CTX format, which is used for "Virtual Textures.")

Celestia looks for texture files in the subdirectories
textures\medres,
textures\hires,
and
textures\lores, in that order.
The older Celestia distribution
include Lores and Medres surface textures
for many bodies in the Solar System. Celestia v1.6.0 includea a few Hires
textures, too.

To select among the three textures in older versions of Celestia,
the key "r" selects the file that
is in the next lower resolution directory, while "R"
selects the file that is in the next higher resolution directory.
Celestia v1.6.0 and newer have appropriate menu items.

Note that the texture images
in these different directories don't actually have
to be different resolution versions of the same image.
The pictures could be completely different from one another. The directory
names and the selection commands are just a
convenience.
[back to Contents]

2.3: Substituting Surface Textures.

When you want to substitute a new texture for an old one,
you have several choices:

"Permanently" Modify the object's catalog entry

Specify an AltSurface that can be selected while Celestia is
running

Select different resolutions

Replace the existing texture.

Edit the object's catalog to specify a different texture.

Discussion:

Preferred:

To "permanently" replace a surface texture, provide an additional SSC
catalog file in the extras directory
which uses the Modify keyword
to specify a different image file name and filetype.

On a computer running MacOS, Celestia's extras directory is likely to
be
/Users/<userid>/Library/ApplicationSupport/CelestiaResources/extras/

This SSC and the replacement image should be in extras
or their own Addon directory. For example, the ssc file
plate_caree.ssc might be in the directory
extras\my_plate_caree\, while the corresponding image file
plate_caree.jpg would be in the directory
extras\my_plate_caree\textures\medres\.

Using the Modify keyword in a new SSC file is relatively
straightforward. Modify should be the first word on the first
line of an object's redefinition. The body of the object's definition
should include the lines that you want to be different
from the original definition. For example, to replace Celestia's
standard surface Texture for the Earth
by the Plate Carré image shown above, one could
use this SSC catalog:

Modify "Earth" "Sol" {
Texture "plate_caree.*"
}

If you want to be able to select among several different surfaces while
Celestia is running, create an SSC catalog to define an Alternate
Surface. See Section 2.4 for details.

Provide an additional image file that has the same name
in Celestia's /textures/hires/
subdirectory. Then you can use r and R
to select among the images in the
/lores/,
/medes/ and
/hires/
subdirectories.

Discouraged:

Replace the existing image file in its /textures/ subdirectory
with a new one that has the same name.

I.e. rename the new file to have the
same name as the original image file. If necessary, you could
convert the format of the new image file to be the same as the
original surface texture image file.
You can leave the format and filetype of the new image file unchanged
if the object's catalog file specifies a wildcard filetype.

Manually edit Celestia's catalog file to specify a different texture
file name (this should be avoided whenever possible).

Although you can edit solarsys.ssc
to change the image file's name when
you want to permanently replace one or more of Celestia's default
planet surfaces with new ones, this is not recommended.
solarsys.ssc is a plain
text file and can be edited with your favorite text editor: Notepad,
Wordpad, emacs, vi, whatever. One problem is that when you install
a new version of Celestia, it will overwrite your changes.
You also run the risk of damaging
solarsys.ssc beyond repair.
Instead, you can either create an AltSurface Addon
that can be selected while Celestia is running,
or you can create an Addon that uses the SSC directive "Modify" to
substitute a different Texture command permanently.

Note:data\solarsys.ssc is critical to the operation of Celestia. Copy it elsewhere first.
It is too easy to make a typographical error which makes the file
unusable. Celestia does not generate any error messages when something
goes wrong. Depending on the problem, Celestia may just skip the bad
directive or it may ignore the rest of the file entirely.
If you have a copy of the original file, you can compare it with your new
version to see what has changed.

Remember that the internal structure of JPG, PNG and DDS files are
quite different from one another. The file extension (the filetype)
is normally used to decide how
to interpret the file. Simply renaming a file from earth.dds
to earth.png will not work. Trying to interpret a DDS
texture as if it were a PNG image will certainly not do what you want.
[back to Contents]

2.4: Alternate Surface Textures.

Starting with Celestia v1.3.1, there is another option for replacing
the surface texture of a body:
Celestia now supports the use of Alternate
Surface Textures.

In an .SSC file, you can specify one or more AltSurfaces which list
textures to be associated with an object. Then when Celestia runs, you can choose
the appropriate set of surface textures by Selecting the object and
then using
the "Right-Mouse-Button-context-menu". Click on the object with
the "Right-Mouse-Button" ("Ctrl-Click" on a Mac). The pop-up menu will include the menu item
"Alternate Textures" whenever there are alternate surfaces associated
with the Selected object. Alternate surfaces can include all of the
qualities associated with surface textures traditionally used for Celestia's
objects, including bumpmaps, specular reflections, etc.
Atmospheric effects with clouds are not
available, however.

When you select a particular AltSurface, Celestia also respects the
resolution selection commands "r" and "R". In other
words, each AltSurface can have as many as three different surface
images, one in each of the lores, medres
and hires directories.

Alternate surface textures can be defined in their own SSC file.
They do not have to be defined in the
same .SSC file with the object that they're associated with.
The SSC file which defines the host body does have to be loaded before
the file contining the AltSurface definition, though, so that
Celestia already knows the body it uses.
An AltSurface declaration specifies its own name plus the
name of the body to which it should be applied.

When you run Celestia and select an AltSurface,
only those surface texture images declared in that AltSurface definition
will be shown.

Surface textures are not inherited from other
declarations for that body. If an AltSurface only mentions a Texture,
no NightTexture will be shown.
The surface textures that can be specified are Texture,
BumpMap (or NormalMap), SpecularTexture,
NightTexture and
OverlayTexture surface map images.
Only CloudMap texture images, which are declared in an SSC's Atmosphere
definitions and are not surface modifiers,
are inherited from the object's "Normal" surface definition.

(Note that the word "Normal" is used ambiguously in Celestia.
NormalMap images are used to define surface shading that changes
as the body rotates.
The word "Normal" also is used to indicate "standard" or "default" surfaces.
These default surfaces are the surface texture images which are
declared in an object's
initial SSC declaration, not in an AltSurface declaration.)

All of the AltSurfaces which have that same name are selected
for all objects when you select an AltSurface with that name for any
object. There is only one AltSurface name active at a time.
It is used to select AltSurfaces for all objects at once.

You can define a different AltSurface texture image for each of
many different objects,
and you can give all of their different AltSurfaces the same
name, "Ancient" for example.

If you select an AltSurface named "Ancient" for the Earth,
and if an "Ancient" is defined for Mars, you will see the AltSurface
"Ancient" when you GoTo Mars. You do not have to select it separately.
Objects which do not have an AltSurface of the
specified name revert to showing their "Normal" surfaces.

For example, this would specify "Ancient" topologies for Venus, Earth
and Mars:

Only the surface textures are affected by the AltSurface
definition.
These are the Texture, BumpMap (or NormalMap), SpecularTexture,
NightTexture, and OverlayTexture surface map images.
CloudMap texture images, which are declared in SSC Atmosphere
definitions and drawn on a sphere above the body's surface sphere,
always are inherited from the object's "normal" (default SSC) surface definition.
They can be changed using the "r and "R" resolution
selection commands or menu options, though. See section 2.2.

Here's an example .SSC file specifying AltSurface maps for Mars.
If it is put in the directory Celestia\extras\MyMars\
then its corresponding surface textures should be in
Celestia\extras\MyMars\textures\medres\.

This SSC uses textures available from my Mars Web page at
gallery-002.html. Mars is defined in
Celestia's solarsys.ssc, so it's already known when
an Addon's SSC file is loaded from the \extras\ directory.

Starting with Celestia v1.3.1, high resolution surface textures
of planets and their satellites can be provided as groups of many
smaller images.
A 32Kx16K surface texture no longer has to be one gigantic file.
Instead of loading one image for the entire surface of an object,
Celestia loads only those images that are needed to display the part
of the surface that you're looking at. As a result, the surface
textures load much more quickly and Celestia runs more smoothly.

(Well, sort of. Often there are so many tiles visible that
loading all of their files individually takes longer
than loading a single larger image file.)

A virtual texture consists of these elements:

A surface texture declaration specifying a .ctx texture

(This declaration must be in a .SSC file. You can modify
solarsys.ssc, but I prefer to use a separate .SSC file in an
Addon directory.)

A .ctx file
declaring the name of the folder
containing the texture image tiles which are components of the
CTX virtual texture.

(The .ctx file is in an apppriate
textures sub-directory, usually either medres or
hires. The folder it specifies is in that same sub-directory.)

As many as 13 levels of resolution (0 through 12) in separate folders

Appropriate image tiles to be drawn by Celestia
at each level of resolution.

2.5.1: Surface Texture pointing to a
.ctx.

The easiest way to use a Virtual Texture is to declare it as an
AltSurface in an SSC file. This SSC catalog file should be in the main
directory that is named for and associated with this VT Addon. While
the SSC catalog file could be
put directly into your /extras/ directory, you will regret that
later.

Here's an example for the Earth.
On my system, it lives in
\extras\Addons\BlueMarble DDS\BlueMarble.ssc.
This SSC catalog specifies the Virtual surface Texture file named
BlueMarble DDS.ctx
along with a NightTexture, NormalMap, and others. The smallest possible
AltSurface would include only the Texture specification.

2.5.2: .ctx specifying tiles.

A .ctx file is a plain text file which describes the
tiles that compose the virtual
texture. The .ctx file goes into the texture\hires
directory associated with this VT Addon,
just as a JPG or PNG image would.
On my system,
it lives in \extras\Addons\BlueMarble DDS\textures\hires\

The .ctx file specifies the name of the next lower
folder of this VT Addon. This next lower folder contains up to 13 folders named level0
through level12. The level folders actually contain the
images that form the tiles of the virtual texture.

For example, here is the file \textures\hires\BlueMarble DDS.ctx
It says that the next folder down,
\extras\Addons\BlueMarble DDS\textures\hires\BlueMarble DDS,
contains the folders of tiles
for this virtual surface texture.

TileSize specifies
the value (in pixels) to be used when calculating when to change
the resolution level of textures being shown in Celestia's display.
It does not necessarily correspond to the actual widths of the
tiles themselves.

There is in fact a "fencepost" problem in the way
Celestia uses this number. If you use a TileSize that corresponds
to the number of pixels in each tile, when a new resolution level is
loaded, the visible resolution improves. This is because the lower
resolution level was being displayed past the point where
its resolution matched the screen resolution. Its pixels were being
blurred across several onscreen pixels.
It's generally best to specify a TileSize pixel
value which is half the width of the tiles. If you have tiles which are
512x512 pixels, specify a TileSize of 256.
The next level of tiles will be loaded when you have reached
the point where the resolution visible on screen matches
the resolution of the lower resolution tiles.

VT tile images do not have to be square, although they do have to be
a power of two on a side. Celestia scales them appropriately. In
particular, this means that you can use rectangular tiles for areas
near the poles. This can save a lot of disk space.

TileType specifies the type of image format used for the
tiles. This can be JPG, PNG, DDS or, in v1.5, DXT5NM.
(See
section 2.6
for a description of DXT5nm normalmaps.)

2.5.3: 13 levels of resolution.

Starting with Celestia v1.4.0pre1, Virtual Textures can use as many as 13 levels of resolution
(0 through 12) stored in separate folders.

BlueMarble folder structure

Contents of
Celestia\extras\Addons\BlueMarble\textures\hires\

Virtual textures consist of as many as 13 levels
(0 through 12) of detail.
Each level corresponds to an image area that is four times
the size of the previous level: twice the width and twice the height.
If level0 consists of two 512x512 images (which is the equivalent of a
1K surface texture) then level1 can contain eight 512x512 images
(the equivalent of a 2K surface texture) and so on.

On the Earth, this means
that level0 has a resolution of about 40km/pixel.
The Earth has a circumference of about 40000 km.
40000 / 1024 = about 40.
If the level10 folder conatains
tiles that are 512x512 pixels, they will provide a resolution
of about 40 meters/pixel. Larger tiles would provide
proportionately better resolution for level10.

Each level
of detail consists of up to 2n x n texture tiles, where
n must be a power of two. Fully populated, each level
would contain 4 times as many tiles as the previous level. Only the
lowest resolution level, level0, must be fully populated,
however. If tiles are omitted from higher reslolution levels, then the
area that would be covered by the missing tiles is filled in from lower
resolution levels.

When placing tiles in a virtual texture with a BaseSplit of 0,
level0 contains two tiles, each covering 180
degrees. Level1 has 8, 90 degree tiles; level2: 32, 45 deg; level3:
128, 22.5 deg; level4: 512, 11.25 deg; level5: 2048, 5.625 deg;
etc. Use the spreadsheet in the
Tools section below
to help in calculating the latitude and longitude of tiles.

Celestia chooses the level of detail to use based on the size in
pixels of the object shown on the screen and the TileSize
specified in the ctx file. The image change is not
based on the actual sizes of the tile images.

When a level is fully populated, the equivalent width of the tiles at that
level is always double the height if they're considered to be a simple
cylindrical projection as used by Celestia. (e.g. 1024x512 or 32768x16384)

The individual tiles
do not have to be square, however.
In particular, the tiles near the poles could be rectangular,
perhaps 2 or 4 times as tall as they are wide. They do have to be
powers of two on a side. Celestia (actually your graphics card)
stretches them to the appropriate size to be projected on the associated
part of the globe.

All the levels of detail do not need to
be fully populated, but the lower resolution level folders do have
to exist. If you have a few high resolution tiles in level7, all of the
folders named level0 through level6 must be there. Level0 should be
fully populated with its two tiles, but the intermediate folders can be
left empty.

If a tile at the requested level of detail is not
available, Celestia will fall back to the next lower level of detail
that's available. This allows you to map planets with very high resolution at
particular locations without forcing you to map the entire planet at
that resolution. For example, the level10 folder below
contains high resolution tiles of the Cape Canaveral
area. You might want to create some for your home town.

2.5.5: VT creation utilities.

Several tools are available to help create Virtual Textures.

Fridger Schrempp wrote a zsh script that cuts large surface texture
images into the desired size tile images. You can download it from
Shatters.net at
http://www.shatters.net/~t00fri/virtualtex.
This script can be used on a Linux system or on a Windows system that
has both Cygwin and ImageMagick installed.

2.6: Normalmaps.

Normalmaps provide detailed information about the roughness of a
surface.

Discussion:

"Surface normal vectors" are pointers which indicate what direction
is perpendicular to the local area on an object. ("Normal" is a
mathematical synonym for "perpendicular".) They
describe the orientation of a region on the surface of a model.
They control both how it is illuminated, including how shadows
are drawn on it, and whether the surface is drawn at all.
Surfaces that have normals pointing toward a lignt are illuminated.
Surfaces that have normals pointing away from a lignt are shaded.
Surfaces that have normals pointing toward the observer have to be
drawn if they are not obscured by another object.
Surfaces that have normals pointing away from the observer
do not have to be drawn.

A normalmap makes a flat region look like it has bumps.
Using a normalmap to describe the shading of a region is much less
expensive (i.e. has better performance)
than using a 3D model containing all of the details of that area.

Celestia can use several different formats of normalmaps.

BumpMap -- an 8bit grey-scale image: a heightmap
which Celestia converts into a normalmap internally. White pixels indicate
the highest regions and black the lowest.

NormalMap -- a file which contains three channels of
information about the surface normal vectors of a surface: the
magnitudes of their x, y and z components.

Normalmaps can be provided as either
RGB color images or (in v1.5 and later) as special DDS/DXT compressed files.
Color images used for normapmaps have a distinctive pink-blue-purple
coloration.

In general, PNG images provide the most accurate normalmaps since
they use a lossless compression. However, they are expensive in memory
and CPU because they have to be decompresed to full resolution before
they can be used. Although they're smaller, JPG and DDS tend to be
worse in accuracy because
their compression algorithms permanently discard or change some of the colors.

When adding a surface normal texture map in a CMOD model, the
model file's vertices must include tangents.
Use cmodfix with the qualifier --tangents.

Celestia v1.5.0 (and later) will support two different NormalMap DDS
formats, both the traditional normalized RGB format and a compressed
format called DXT5nm. Normalmaps provided in DXT5nm
format must have the .dxt5nm filetype. When DXT5nm format normalmaps
are used as a Virtual Texture and declared in a .ctx file, the
TileType must be declared to be "dxt5nm". This new format is visible
only in Celestia's "OpenGL 2.0" render path. It requires
graphics hardware that supports OpenGL v2.0.

V8.22 and later of Nvidia's nvdxt can generate this new compressed
format:

nvdxt -quality_highest -file *.png -nomipmap -dxt5nm

It copies r->alpha, g -> r,b and then DXT5 compresses the result.

ImageMagick v6 and later includes an enhanced convert
utility which can
operate on individual layers using the -channel and -fx qualifiers.
Although slower, this can be used with other utilities to produce
normalmaps in this new format.

A procedure for generating 3-channel normalmaps from photographs
with special orientations is described at
http://66.70.170.53/Ryan/nrmphoto/nrmphoto.html.
It includes a program for converting normalmaps into bumpmaps.
However, Celestia's progression has been from the use of
Bumpmaps, which use a relatively low 8bit resolution,
to higher resolution (24bit) Normalmaps.

Bumpmaps can be converted to (low resolution) Normalmaps using ATI's
utility.

3.0: Uses Within Celestia (What to use them for).

Sections 3.1 through 3.5
describe the uses of
texture images within a SSC (Solar System Catalog) file. They are used
for Planets, Moons, Asteroids, Comets and Spacecraft.
The final two sections, 3.6 and 3.7,
describe
how surface textures are used within a DSC (Deep Space Catalog) file
for Nebula objects and in an STC (STar Catalog) file for
Star objects.

3.1: Object Surfaces.

You can define new surface colorations for spheres or models by using the SSC directive
Texture "imagefilename"

To change the appearance of a planet, replace its texture map or change
its Texture declaration in the appropriate .SSC file. The planets of
the solar system and their associated Textures are defined in
data\solarsys.ssc. Don't modify that file if you can avoid
it, however. Instead, create a new .SSC file in your
extras directory which uses Modify or defines
an AltSurface. See Section 2.3.

If you provide a PNG image or a DDS texture, it can include an Alpha
channel in addition to its primary image. Celestia uses that Alpha channel
to define the specularity (reflectivity) of the surface:
white makes it bright over oceans and black makes it dull over land areas.
If the Texture image does not include an
Alpha channel, you can use a separate image to define the surface specularity.

If you provide a JPEG image as the surface texture, it will define only
the surface coloration. JPEG images cannot include Alpha channels, so a
separate image must be provided if you want to define the surface specularity.
See below.

Texture
declarations in SSC and STC catalog files
can be used for Celestia's spherical bodies and for
CMS, CMOD and 3DS models.

3.2: Specular Reflections, Mountains
and Night Lights.

You can change the appearance of a spherical object like a planet by providing
the different types of textures described below.
Unfortunately, only the basic
surface Texture works for CMS, CMOD or 3DS models. The other types of
texture files don't do anything when applied to CMS, 3DS or CMOD models.

Example Earth, showing

nightlights in Europe

specular reflections in the western Atlantic

Click on this Cel:// URL to cause Celestia to take you to this viewpoint:

If your graphics card supports Multitextures, you'll be able
to see the European city lights. If your graphics card supports
OpenGL vertex programs, the western Atlantic will be lit up.
If Celestia shows that highlight, then it also will show shadows
on mountainsides and on crater walls. You may need to type Ctrl-V
several times to cause Celestia to select the advanced Rendering options.

Although Celestia can be used with any graphics card, it needs
certain advanced 3D rendering features in order to display
some of its "eye candy." Type a Ctrl-V several times to get Celestia to
step through the rendering options available on your computer
while displaying their names.

3.2.1: Specular Reflections.

A specular reflection happens when sunlight reflects off a smooth
surface, glinting off the sides of waves on a body of water, for example.
On a 3D model, a specular reflection is represented by a highlight.
The graphics hardware doesn't actully show reflected images.

For Celestia to display specular reflections, your graphics card
must support "OpenGL vertex programs". If you can see specular
reflections, you'll also see the effects of BumpMaps and
NormalMaps.

A SpecularTexture defines areas of a surface which can cause
reflections of sunlight. Celestia uses one for the Earth
to simulate the Sun reflecting off the Earth's oceans, for example.

You can create specular reflections on a sphere or model by using the SSC directives
SpecularTexture "imagefilename"SpecularColorcolor (no default; 3 numbers in [ ] )
SpecularPowernumber (default = 0 = no specularity)

Specular reflection textures are grey-scale images which are white
where reflections are the brightest and black where there should be
no reflection.

If you create a surface texture that has an Alpha channel
and use it for a planetary body, that Alpha channel
is treated as a specular reflection texture and you don't need
a separate file for it, and you don't need to provide a
SpecularTexture declaration.

If only SpecularColor and SpecularPower are present,
and no Alpha channel is present in the surface texture,
the entire surface of the body is treated as if it were smooth and
shiny.

SpecularTexture declarations in SSC catalog files
only work for spherical bodies.
They don't work on CMS, CMOD or 3DS models.
However, specular surfaces can be specified for models by using
appropriate material definitions within them
if you're running Celestia v1.5 or later.

3.2.2: Mountains and Craters.

The wrinkles in mountainous surfaces can be made apparent by using
either a BumpMap or a NormalMap. Their sunlit sides will be bright and
their shaded sides will be drawn darker. Celestia does not support
self shadowing as a result of bumpmaps, though, so
they won't cast shadows across other parts of the landscape.

For Celestia to display shadows due to bump or normal maps, your graphics card
must support "OpenGL vertex programs".
If you can see
the effects of BumpMaps and
NormalMaps, you'll also see
specular reflections.

To apply a BumpMap to the surface of a sphere, use the SSC directives
BumpMap "imagefilename"BumpHeightnumber (default = 2.5)

For a Bumpmap, provide a grey-scale image that's white at the highest
altitudes and black at the lowest. Although Celestia can use only an
8bit greyscale image, development of a bumpmap using more bits
per pixel can produce a better result when you finally reduce it for
use with Celestia.

Internally, Celestia converts bumpmaps into normalmaps for use by
your graphics hardware. Since bumpmap images can contain only 256
height values,
this may cause problems when displaying a surface at high resolution.
You can provide your own NormalMap to improve on this.

BumpMap
SSC declarations only work for spherical bodies.
They don't work on CMS, CMOD or 3DS models. Also, bumpmap textures
do not work in material definitions in models. Use normalmaps instead.

To apply a NormalMap to the surface of a sphere, use the SSC directive
NormalMap "imagefilename"

For a NormalMap, provide a full color image. The R, G and B channels
define the amplitudes of the surface normal vectors in the X, Y and Z
directions respectively for each pixel.

In this usage, "Normal" is an abbreviation for "Surface Normal
Vectors". They're the directions which are perpendicular to the
wrinkled surface at each pixel's location. (Celestia also uses
the word "Normal" to indicate the default surface texture when AltSurface
textures are in use. This can be confusing at times.)

NormalMap declarations in SSC catalog files only work for spherical bodies.
They don't work on CMS, CMOD or 3DS models.
However, materials in models can specify
normalmaps for use with Celestia v1.5 or later.

3.2.3: Night Lights.

A NightTexture is used to color the dark side of a sphere. Brightly
colored areas look like lights on the surface.

For Celestia to display night lights, your graphics card
must support "Multitextures."

To draw nightlights on a sphere, use the SSC directive
NightTexture "imagefilename"

Provide a colored texture that includes an Alpha channel.
Just as with a CloudMap, this Alpha channel defines the
opacity of the texture map. The Alpha channel should be opaque
(white) where there are lights and transparent (black) where there
are no lights.
If your NightTexture does not include an Alpha channel, it will still work,
but the body's surface Texture won't be visible on the night side. Only
the NightTexture will be visible on the night side of the body.

NightTexture declarations in SSC catalog files
only work for Celestia's default spherical bodies.
They don't work on CMS, CMOD or 3DS models. However, models can contain
emissive material definitions, which are equivalent, for use with Celestia v1.5 or later.

3.3: Overlays and the Limit of Knowledge.

Some areas on some of the planets and moons have never
been photographed. We really don't know what most
of the surface of Mercury looks like, for example.
Celestia includes several pictures of bodies that have had the
unknown areas filled in with artistic guesses.
Opaque overlays can be added to cover the areas that we've never seen.

For Celestia to display overlays, your graphics card
only needs to support "Basic" rendering.

To apply an OverlayTexture to a sphere, use the SSC directive
OverlayTexture "imagefilename"

An OverlayTexture can be used to blank out the unknown areas of a
sphere. This helps to distinguish the valid surface information from
the imaginary imagery that has been used to fill in the empty space.

Provide a colored texture that includes an Alpha channel.
Just as with a CloudMap, this Alpha channel defines the opacity
of the texture map. Where the opacity channel is black, you can
see the underlying surface texture. You can see the OverlayTexture's
coloration where the opacity channel is white.

The OverlayTexture is drawn on top of all of the other surface
textures, beneath the CloudMap.

An OverlayTexture often is used within an AltSurface declaration
called "Limit of knowledge". Many are included in Celestia's
solarsys.ssc

OverlayTextures only work for spherical bodies.
They don't work on CMOD, CMS or 3DS models.
However, an AltSurface Texture can be used instead of an
OverlayTexture
to specify an
appropriate replacement surface texture image for the entire surface of a model.

There is a bug in Celestia v1.4.1 which prevents
OverlayTextures from being drawn in "Render path: OpenGL 2.0".
Overlays do work in the other Render paths. This bug has been fixed for v1.5.

3.4: Clouds.

A Cloud layer defines a partially transparent layer that can move
across the surface of an object.

For Celestia to display clouds, your graphics card
only needs to support "Basic" rendering.

For Clouds, use these directives within an SSC's
Atmosphere declaration:
CloudMap "imagefilename"CloudHeightnumber (km)
CloudSpeednumber (deg/day)

Provide a colored texture that includes an Alpha channel.
This Alpha channel defines the opacity
of the texture map. Where the opacity channel is black, you can
see through the clouds to the underlying surface texture.
You can see the colors of the CloudMap's
image where the opacity channel is white.

The CloudMap is drawn after the OverlayTexture.

Clouds for the Earth usually are defined as a completely white image
plus an opacity channel that defines the shapes of the clouds.

An Atmosphere declaration works fine for CMOD, CMS and 3DS models, so
you can have Clouds flowing around them. Clouds are always drawn
on a sphereoid, so this can look a little strange.

The size of a CloudTexture image used for moving clouds is limited
to the size of your graphics
card's texture buffer. This might be 1K, 2K or as much as 4K pixels
on a side.
If you specify a CloudSpeed of 0, however,
then the CloudTexture can be any
size, or even a VirtualTexture.

Features new with Celestia v1.5.0 and later:

shadows are cast under clouds

CloudNormalMapstring: "your-cloud-normalmap.png"

Either normalized PNG or DDS/DXT5nm compressed normalmaps can be
used. Normalmaps with filetypes of PNG, JPG or DDS must be provided
in a normalized format (vector length = 1). Normalmaps provided in DXT5nm
format must have the .dxt5nm filetype. When DXT5nm format normalmaps
are used in a Virtual Texture (.ctx file), the TileType must be
declared to be "dxt5nm".
Normalmap tools to develop DXT5NM textures for Celestia are available
at
http://www.celestialmatters.org/.

3.5: Rings.

A Ring texture is a linear image which defines a partially transparent
system of circles around a planet. Each opaque pixel is drawn as a
circle. Transparent pixels can be seen through.

For Celestia to display rings, your graphics card
only needs to support "Basic" rendering.
To display planet shadows on Rings, Multitexture support is required.
However,
to project ring shadows onto the planet, your graphics card
must support "OpenGL vertex program" rendering.
(Even so, Nvidia MX cards cannot draw ring shadows on planets. They
can draw only the shadow of the planet on the rings.)

The definition of Saturn in Celestia's catalog file /data/solarsys.ssc
shows how these declarations should be structured.

The Texture image used for the rings around a planet should include
an alpha channel in addition to the primary image.
The primary image determines its color and brightness.
The alpha channel determines its opacity.
These images typically are long and skinny: 512x16 and 1024x64 are common
sizes. The width of a texture image used for a Ring's Texture
is limited to the size of your graphics
card's texture buffer. This might be 1K, 2K or as much as 4K pixels
on a side.

Most of the image file actually isn't used. Celestia only
expands its first raster line. That scanline is used to define the ring's appearance
along a radius: along a line extending outward from the center of the
planet. Celestia expands it in a circle around the planet's equator
to produce the final image.

3.6: Nebulas.

To display Nebulas, your graphics card only needs to do "Basic"
rendering.
For older versions of Celestia, you have to remember to turn on "Show Galaxies" in
Celestia's "View Options" menu, keyboard shortcut "u".
For Celestia v1.4.0 and later, you have to remember to turn on "Show Nebulae" in
Celestia's "View Options" menu, keyboard shortcut "^" (caret: "^ space" on
keyboards that support diacritical marks).

A Nebula's surface texture is not specified explicitly within a DSC
(Deep Space Catalog) file: DSC files may not contain any Texture
directives. Instead, the names of
the image files
used to color a Nebula must be specified within its 3DS or CMOD model.
Nebulas cannot use AltSurface textures.

A Nebula's texture image file may be any of the image file types
supported by Celestia except for CTX virtual
textures. Like Ring textures and moving Cloud textures, though,
the size of a Nebula's surface texture image is limited
to the size of your graphic
card's texture buffer. This might be 1K, 2K or as much as 4K pixels on
a side.

If the texture file includes an Alpha channel, the
Alpha channel is a grey-scale image which defines the opacity of
the surface coloration.

Depending on the 3D design program you use, you may not be able
to specify the type of image file that you need to use with Celestia.
Many 3D design packages do not directly support the use of DDS texture
files, for example. In such cases, you will have to edit the 3DS model
file using a binary file editor to change the texture file name.
(I use Emacs.)
Making this change usually isn't very difficult.
The surface material specifications usually are
near the beginning of the 3DS model file.

If you use 3DSTOCMOD to translate the 3DS model into a CMOD ASCII file, of course,
any text editor can be used
to change the names of the surface texture image files declared within
the ASCII CMOD model file.

4.0: Common Problems.

Unfortunately older versions of Celestia don't provide much help when things go wrong.
This has changed starting with Celestia v1.3.1, which includes an
error message display. Type a "tilde" (~) to see it. (European
keyboards require a space after the tilde.)

When there are problems with a surface texture,
Celestia will draw
the object without that surface texture.
This usually results in a dull white or black ball.
For example, if it draws Mars
as a dull pink ball, that means that no
surface texture has been loaded.

This will happen if you provide an image file of the wrong
type or size, or if you specify the name of a texture file that
doesn't exist, or if you've
filled up the memory in your graphics card.

Check the image file: it could be
the wrong format or the wrong size.

Make sure that the image really is what you think it is: JPG, PNG or
DDS. The filetype extension of the file name must be correct for the
type of file that it is.

Make sure that it is a format that your graphics card can display.
DDS texture files can only be shown by cards that were designed in the
past few years. Cards made by 3dfx, for example, can't show them.
Microsoft's software OpenGL routines can't draw them, either.
Microsoft's software OpenGL is what is used under Windows if
you disable your graphics card's hardware acceleration.

Make sure that the image size is a power of two on a side: 1024x512 or
4096x2048, for example.

Check your SSC to make sure the file name is OK

A crosshatch (#) in solarsys.ssc
(or in any catalog file, for that
matter) means "ignore the rest of this line". Make sure there is no #
in front of the Texture declaration you want. There must be only one
active Texture declaration for each planet definition: make sure there
is a # in front of every other Mars Texture definition that you've left
in.

Check to make sure you have not made a typographical error in the
Texture file name. It must be enclosed in quotes (").

Also make sure that the image is small enough to fit into
the memory on your graphics card. A PNG image that's 8Kx4K requires a card
that has more than 8K*4K*4 = 128 MegaBytes of memory. DDS image
textures don't need that much room on the card. The graphics chips
that can use DDS images store the file directly on the card and
do the decompression themselves.