This Web page is too long to be completely translated by BabelFish. It is now available in shorter sections starting at http://www.lepp.cornell.edu/~seb/celestia/addon-intro-p0.html
The second edition of "Introduction to Addons" was updated for Celestia Version 1.3.0 (and later). Several new features are available which make it a lot easier to keep track of the Addons you've installed and to move them to the next version of Celestia. Older Addons still work, but if you're willing to change them a little, they'll be much easier to use and understand.
This third edition was updated to include a relatively simple Nebula Addon for NGC 3372. It's more complicated than the star and planet Addon but not as demanding as Rassilon's Rosetta Nebula Addon. Also, a section has been included which tries to provide help for common problems.
Some of these example Addons describe imaginary objects. There really is a Rosette Nebula, but we really don't know its three-dimensional shape. Also, we know nothing about whatever planetary systems might be in it.
Here's a general overview of how Addons are supposed to work:
Most Addons consist of 1, 2 or 3 sets of files:
1.1:
One or more Catalog files. These describe where the objects are in space.
1.2:
Surface pictures (texture maps) for those objects. These give the objects a
unique appearance.
1.3:
Models of the objects. These give them special shapes.
1.4:
File locations. Each type of file goes into a particular directory.
Although they're all plain text files, different keywords are used in the different types of Catalog files. You can't rename a .SSC file to be a .STC file, for example.
Celestia tries to load all of the STC, DSC and SSC files that it finds, in that order. The first part of a Catalog file's name also determines the order in which it is loaded. Catalog files of each type are loaded in alphabetical order under Windows. Under Linux and MacOS, however, you can't always depend on this. As a result, it's best to define all stellar objects in a single STC file and all planetary objects in a single SSC file.
Celestia only reads in Catalog files when it starts up. If you modify an old file or add a new Catalog file, you have to exit from Celestia and start it up again so it can find the new file.
Unfortunately, some Addons don't include a Catalog file. Their authors leave it up to you to create one.
Celestia includes its own SSC files in its \data\
directory
to define the solar system:
all of the planets
and many of their moons, along with asteroids, comets and a few
spacecraft. The solar system's planets and moons are defined in the file
named solarsys.ssc
in Celestia's data
directory. The catalog file extrasolar.ssc
lists most of the exoplanets
that have been discovered orbiting other stars.
For more details about the contents of the catalog files, please read the following documentation:
Many people enjoy improving how planets look, making replacement surfaces for existing planets or moons. This includes not just surface texture images, but also images for bumpmaps, specular reflections and clouds. Starting with Celestia v1.4.0, surface texture images also can be used to modify the appearances of individual stars.
Warning: to see these new planet surfaces, the instructions that come with older Addons often suggest that you rename the new image files to replace the ones specified in the appropriate .SSC file, or that you edit the .SSC file so it looks for the name of the new surface texture file. Although they'll work, neither of these suggestions is appropriate for recent versions of Celestia (v1.3.0 and later). It's better to create an SSC file that contains AltSurface declarations.
Celestia comes with many surface textures already
in the medres
and lores
directories.
Starting with Celestia v1.5.0, a few hires
textures
are included, too. It's best
not to mix your images among those that Celestia provides. Use a
separate subdirectory instead. See Section 1.4 below.
Modifying the catalog files or directly replacing the surface texture images that come with Celestia will cause a lot of confusion when you upgrade to the next new version of Celestia. Creating an Addon that consists of a separate .SSC file containing an AltSurface declaration pointing to one or more separate texture files is the most trouble-free way to incorporate new surfaces for your planets.
Objects with complicated structures can be created using a 3D design package. Celestia can understand models that are defined in the 3DS binary file format or its own proprietary CMOD format. The 3DS format was originally used by the 3D modelling software named "3D Studio Max". Most 3D design programs can create 3DS files if you use their "Export" command. The current version of "3D Studio Max" uses a format called MAX. Celestia does not understand MAX format.
3D models of objects in STC or SSC catalogs' Mesh statements either may specify particular surface texture files in the material definitions within the models or they may accept a surface Texture specified in the catalog. A Texture declaration replaces all of the textures specified within a model by the specified texture image file.
3D model files that are used to define Nebulas in DSC catalogs must contain the specific names of whatever surface texture image files they need. DSC catalog files may not include "Texture" declarations.
When a model contains a "*" or "*.*" file specification, then its surface texture image must be specified in a catalog using the Texture directive.
When loading a texture specified in a Texture directive,
Celestia first will look for a matching texture image file in
the medres
,
lores
and hires
directories, in that order.
In older versions of Celestia, the "r" and "R" commands also may be used to switch among
those directories.
In v1.6.0 and later, use the menu item Render --> Texture Resolution.
When loading a texture specified in a material in a 3D model,
Celestia loads those images only from a textures\medres
directory. The texture resolution commands are ignored.
Starting with Celestia v1.5, objects and models can be animated if one writes appropriate ScriptedOrbit and ScriptedRotation functions. Describing the use of these functions is beyond the scope of this document.
Celestia v1.3.0 (and later) lets you organize your Addon files. Previous versions
of Celestia required that the files be mixed in with the ones that come
with Celestia.
As a result, many older Addons put their files into the
directories that Celestia uses itself: extras
,
models
, and
textures
This causes lots of confusion when you install a
new version of Celestia.
Starting with Celestia v1.3.0, Addon files can go into a separate
Celestia subdirectory (folder) that you
create within Celestia's extras
directory.
Celestia automatically searches though all of the directories
that are within the extras
directory, looking for catalogs
of objects.
On a computer running Windows 7, Celestia's extras
directory might be
either
C:\Program Files (x86)\Celestia\extras\
or
C:\Users\<userid>\AppData\Local\Celestia\extras\
On a computer running MacOS, Celestia's extras
directory is likely to
be
/Users/<userid>/Library/ApplicationSupport/CelestiaResources/extras/
The descriptions of directories in the examples below all assume that you're using a computer running Windows. Hopefully MacOS and Linux users will be able to determine the actual directories to use.
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.
Now when you install a new version of Celestia, you can simply drag
that whole Addon directory into the
extras
directory of the new version of Celestia.
You no longer have to keep track of which files you added, which ones belong
to which Addon, and which came with Celestia.
Here's one way to organize Addons:
extras
directory
which has the name Addons
.
This will let you move all of your Addons at once by moving just
this one directory.
Addons
directory, create a directory for
each Addon when you install it. For example, you might create the
NGC2237
directory.
NGC2237
directory, you must create the directories
for
its models and its surface textures: create the directories
models
and textures
.
Within the
textures
directory, create the directories
medres
,
lores
and
hires
.
Note: these directory names all must be spelled with lower case letters. Do not capitalize them. Although Windows ignores capitalizations, MacOS and Linux do not.
o (Most Zip programs will recreate the subdirectories and their contents as provided by the author.of an Addon so that you don't have to create them yourself.)
When you've finished, your directory structure might look something like this:
NGC2237
itself.
An older Addon, one which was created before this new directory
layout became possible, usually includes an \extras\
directory containing all of its catalog files.
Those files all must be moved into
the Addon's main directory and the
folder \extras\
that was provided with the Addon
should be deleted.
\textures\
directory.
Most Addons come with just one texture resolution. Their pictures normally go
into the medres
directory. For example, NGC2237.png
should
go into the directory NGC2237\textures\medres
.
Texture images for planets and moons can go into any of the subdirectories
medres
, lores
or hires
that are in a Celestia subdirectory named textures
.
When a Texture file is specified in a catalog,
Celestia will look in all three directories while trying to find it,
starting with the medres
, then lores
, then finally
looking in the hires
directory.
If there are texture files with the same name in more than one of the
textures
subdirectories, you can toggle among them using the "r" and "R"
keyboard commands.
In v1.6.0 and later, use the menu item Render --> Texture Resolution.
\data\
directory within that main
directory. (No .xyz or Spice trajectories are used by any of the examples shown here.)
\scripts\
subdirectory, although this is not required.
(No scripts are used by any of the examples shown here.)
\models\
subdirectory.
For example, NGC2237.3ds
goes into the directory
NGC2237\models
.
When a 3D model specifies a texture map file name of "*" or "*.*",
the name of an appropriate texture file must be specified in a
catalog using the "Texture" declaration. Celestia looks for those files
in all three of the associated texture directories:
medres
,
lores
,
and hires
.
When a 3D model contains materials that specify
texture map file names, those
texture files must go into the associated \textures\medres\
directory.
Celestia
does not yet select among different resolution surface
textures if the filename is explicitly specified in a 3D model file.
\celxx\
directory
within the Addon's main directory.
Starting with Celestia v1.5.0, you can use the Lua programming
language to write your own
orbital and rotational functions to place your objects within Celestia.
These modules should be placed in the Addon's subdirectory
\celxx\
.
No examples of ScriptedOrbits or ScriptedRotations are included here.
See the
Celestia WikiBook
for more information about ScriptedOrbits and ScriptedRotations.
When you create an Addon, Please make sure that the names of texture files and model files agree exactly with the names you use in their Texture and Mesh declarations. If a letter is upper cased in the declaration, make sure it's upper cased in the name of the file itself.
Note to Linux users:
The DSC catalog NGC2237.dsc
below violates this. It specifies
the Nebula Mesh to have the filename
NGC2237.3ds
. However, the file provided is named
NGC2237.3DS
. Those names are not the same, and
Celestia will not be able to locate the texture file.
You must rename the file to be spelled
with lower case letters in its filetype so Celestia can find it.
Much more complicated examples of STC and SSC catalogs are included in section 5: Installing an Addon of Stars and Planets.
This Addon consists just of a star with a single planet orbiting around it. It uses a STar Catalog (STC), which tells Celestia where to draw the star, and a Solar System Catalog (SSC), which tells Celestia where to draw the planet around the star.
To keep this simple, the Addon uses surface textures provided with Celestia.
For this and other Addons to work properly, you should download and install Celestia v1.3.0 (or a newer version) if you haven't already done so. Many Addons require the newest version of Celestia in order to work. Nebula definitions, for example, can't work with version 1.2.5. See section 7 for details.
As the first step in this Addon, create the directory
\extras\Addons\HIP500000\
(That's "HIP5" followed by 5 zeros.)
Your directory structure might look something like this:
(The HIP500000 directory does not need any subdirectories. The surface texture this Addon uses is one that comes with Celestia.)
Within the HIP500000 directory, create two Catalog files:
2.1: A STar Catalog (STC), which tells Celestia where to draw the star.
2.2: A Solar System Catalog (SSC), which tells Celestia where to draw planets
around the star.
Imaginary stars can be given fake Hipparcos numbers in Celestia, in which case you should use numbers between 300000 and 600000 to avoid conflicting with stars which have been assigned real Hipparcos catalog numbers.
Here is a very simple STC file which defines a star with the Hipparcos number 500000 and the name "Intro".
Put this STC file into the directory
\extras\Addons\HIP500000\
This STC file contains the information Celestia needs to draw a star. However, Celestia ignores everything on a line after the #. Those are "comment lines". They can be left out if you want.
If you type this in by hand, be sure to get the Capitals and spaces right. "{" and "}" are the letters "shift-[" and "shift-]" These squiggly-brackets are important: they tell Celestia where the definition of each object begins and ends. This is similar to C or C++, but Celestia does not use a semicolon ";" to separate statements. I usually use "Select-and-Paste" commands so I know everything got copied exactly right.
This STar Catalog entry defines a name (Intro) for the star in addition to a Hipparcos catalog number. A star's name must follow the Hipparcos number, be enclosed in quotes, and come before the first "{". More than one name can be specified between the quotes if they're separated by colons (:).
More information about the characteristics that can be declared when defining a star is on the Web page STC Parameters Recognized by Celestia v1.4.0 or Later
####################### #hip500000.stc ####################### # HIP 500000 500000 "Intro" { # fake HIP id number & Star "name" RA 98.0 # J2000 Right Ascension in degrees Dec 5.04 # J2000 Declination in degrees Distance 5500 # Distance from Sun in Light Years SpectralType "G0" # MK spectral and luminosity classification AppMag 15 # Apparent visual brightness } #######################
Notes:
You could use the following procedure under Windows, for example. It uses the default text editor, usually Notepad if you haven't changed any of Windows' settings. Do not use a word processing program like Microsoft Office Word or OpenOffice Writer. They insert binary document formatting commands which Celestia does not understand.
Celestia\extras
Celestia\extras
, press and release the right-most mouse
button.
New...
Text Document
and left-click on it.
HIP500000.STC
and press [return]
three (3)
times to change the filetype and to open the file with Notepad .
File
menu,
Save
option
Exit
option.
Under Windows XP, to associate Celestia's filetypes with a text editor so that they don't get changed, you can follow this procedure:
If you're using Windows Notepad, you may have to use the "Save As". menu item. In the "Save as type" field, select "TextDocument". In the "Encoding" field, select "ANSI".
If you're using Word, you may have to use the "Save As" menu item. In the "Save as type" field, select "Text Document".
Windows may add ".txt" to the file name when you exit from the editor. Be sure to remove it. The filetype must be ".STC".
If you're using Windows, usually pasting into Word will mess it up by putting it all on one line. Pasting into Notepad usually does the right thing.
Archive: HIP500000.ZIP Length Date Time Name -------- ---- ---- ---- 211 04-20-03 12:15 hip500000/hip500000.ssc 187 08-02-06 12:13 hip500000/hip500000.stc -------- ------- 398 2 filesNow your directory structure should look something like this, with hip500000.stc in the folder HIP500000:
Now start Celestia and type the commands
[return]
HIP 500000[return]or
[return]
Intro[return]
[return]
stands for the large "Carriage-Return" key
at the right
edge of the main part of your keyboard. Sometimes it's labeled
"Enter".
[return]
, Celestia will
prompt with "Target name:". It wants you to type the name of the object
to be "Selected". You can type just another
[return]
if you don't want to change the selection.
This star's identifiers (Intro / HIP 500000) should appear in the top left corner of Celestia's window. This means that the star is "Selected".
Now type a "G
" to GoTo that star.
Celestia should turn and go flying to it. You should see a brightly glowing
star just like our Sun, with sunspots but no planets.
Exit from Celestia.
You could change the file so the planet orbits any star you want, of course. If you change the name of the star listed in it from "HIP 500000" to "Sun", Celestia will draw this planet "b" around our own sun instead.
Put this .SSC file into the directory
\extras\Addons\HIP500000\
where you already put hip500000.stc
.
This .SSC file only includes the barest minimum of declarations that Celestia really needs for it to draw a planet. All of the other things that people put into .SSC files just make a planet look better or make it follow precisely the orbit that astronomers have measured.
The lines starting with a # are not needed. They're known as "comment lines." Everything on a line following a # is ignored by Celestia.
If you type this file in by hand, be sure to get the Capitals and spaces right. "{" and "}" are the letters "shift-[" and "shift-]" These squiggly-brackets also are important: they tell Celestia where the definition of each object begins and ends. I usually use "Select-and-Paste" commands so I know everything got copied exactly right.
Here's the format of this particular Solar System Catalog:
######################### # name of SSC file (this line is a "comment") ######################### "name of this planet" "name of existing star" { Texture "picture.jpg" # name of surface texture image file Radius 64000 # equatorial raduius in kilometers EllipticalOrbit { Period 5.8 # length of year in Earth years SemiMajorAxis 2.5 # radius of orbit: multiple of Earth orbit size } } #########################
More information about Solar System Catalog (.SSC) files is available in
Creating SSC files.
This simple Addon makes use of Celestia's existing planet surface
texture image jupiter.jpg
, but you could create your own.
Descriptions of some of the features of Celestia's support for
surface texture images can be found in
textures.html.
######################### # hip500000.ssc ######################### "b" "HIP 500000" { Texture "jupiter.jpg" Radius 64000 EllipticalOrbit { Period 5.8 SemiMajorAxis 2.5 } } #########################
Now your directory structure should look something like this:
Now start Celestia and GoTo HIP 500000 as you did in step 2.1 above.
Open the menu "Navigation" "Solar System Browser" after you GoTo the star. It should list all of the planets around the star: just "b" in this case.
GoTo the planet. Play with the Render settings.
Here's a snapshot taken by Celestia of this solar system:
HIP 500000 and its planet "b" |
Here are some Cel://URLs to take you to this viewpoint.
Unfortunately, the locations in URLs changed in recent versions of Celestia.
|
Just to be whimsical, here's an SSC catalog which places a spacecraft orbiting planet "b". Perhaps some interstellar explorers dropped off a copy of our Galileo probe on their way through the system!
Since this Addon does not include a \models\
directory
containing a model file named galileo.3ds
, Celestia will
use the model that's in its main \models\
directory.
Under Windows, Celestia loads SSC files in alphabetical order. Since this
spacecraft.ssc
refers to the planet b
,
the name of this SSC file must be alphabetically after the name
of the SSC file which defines b
. Fortunately,
the name hip500000.ssc
comes alphabetically before
spacecraft.ssc
! Under other operating systems, the SSC files might
not be loaded in the correct order, however. In that case, you should
include the definition below at the end of your original SSC file.
######################### # spacecraft.ssc ######################### "spacecraft" "HIP 500000/b" { # full "path" to this planet "b" Class "spacecraft" # controls color of orbit path & label Mesh "galileo.3ds" # the name of the 3DS model Radius 0.01 # measured in km: 10 meters for this EllipticalOrbit # units are different when orbiting a planet { Period 64 # measured in Earth days SemiMajorAxis 4700000 # measured in km } } #########################
I'll assume you're using some version of Windows, although equivalent operations should work with the MacOS X and Linux versions of Celestia.
If you've ever downloaded and installed other software, I'm sure this description will be full of things you already know how to do. You should be able to use similar procedures for other Addons.
Essentially, the steps are:
3.1: Download the Zip archive file containing the Addon you want
3.2: Create the directory tree to contain the Addon.
3.3: Copy the Addon files from the zip archive to the
appropriate Celestia directories
3.4: Start Celestia and view the object.
In detail:
Archive: ngc3372.zip Length Date Time Name -------- ---- ---- ---- 0 10-07-03 19:23 ngc3372/ 217 10-07-03 19:19 ngc3372/eta-car-130.stc 236 10-07-03 19:19 ngc3372/eta-car.stc 0 10-07-03 19:23 ngc3372/models/ 709 10-07-03 16:05 ngc3372/models/ngc3372.3ds 1565 10-07-03 19:23 ngc3372/ngc3372-readme.txt 534 10-07-03 16:03 ngc3372/ngc3372.dsc 0 10-07-03 19:23 ngc3372/textures/ 0 10-07-03 19:23 ngc3372/textures/medres/ 241637 04-13-03 15:49 ngc3372/textures/medres/ngc3372.jpg 5120 10-07-03 19:18 ngc3372/textures/medres/Thumbs.db -------- ------- 250018 11 files
If you want, however, you can create all of its directories by hand and then drag the files individually from the archive into them. Here are the details of this manual procedure:
extras
directory
which has the name Addons
.
This will let you move all of your Addons at once by moving just
this one directory.
Addons
directory, create a directory for
each Addon when you install it. For example, you might create the
NGC3372
directory.
NGC3372
directory, you must create the directories for
its models and its surface textures: create the directories
models
and textures
Within the
textures
directory, create the directory
medres
.
(The lores
and hires
directories aren't needed
for this particular Addon.)
When you've created the new directories, your directory structure might look something like this:
You need to have a ZIP program installed to extract the files. (Windows XP, Vista and 7 come with one built in.)
This Addon has 4 components:
ngc3372.dsc
,
eta-car.stc
,
ngc3372.3ds
, and
ngc3372.jpg
.
All of the Catalog files for an Addon, whether they're .STC, .DSC or .SSC, go into the same "root" directory.
[back to Contents]
ngc3372.dsc
.
This is the "Deep Space Catalog" which defines the Nebula's name
and location, the model to use and the nebula's size.
Drag it to the Celestia subdirectory
extras\Addons\NGC3372\
or you can use this copy:
###################### # NGC 3372 # # The accompanying image of NGC3372 was derived from 02192.TIFF # at http://www.noao.edu/image_gallery/html/im0061.html # Original tiff image credit: # "National Optical Astronomy Observatory/ # Association of Universities for Research in Astronomy/ # National Science Foundation" # Nebula "NGC 3372" { Mesh "ngc3372.3ds" Axis [-0.206916 0.153726 0.966206] Angle 154.5 Distance 8500 RA 10.7345 Dec -59.752 Radius 219 InfoURL "http://www.noao.edu/image_gallery/html/im0061.html" } ######################
Alternatively, here's a link to a copy of this file that you can download:
eta-car.stc
and eta-car-130.stc
.
These are "STar Catalogs". They define the incredibly bright
variable star Eta Carinae which illuminates the nebula.
eta-car-130.stc
should be used with Celestia v1.3.0.
If you have a later version, like Celestia v1.4.0,
then you should use the file eta-car.stc
.
Drag the appropriate STC file to the Celestia subdirectory
extras\Addons\NGC3372\
.
or you can use this copy:
# Eta Carinae -- a high luminosity irregular variable 500002 "Eta Car:HD 93308" { RA 161.264958 Dec -59.684517 Distance 8500 SpectralType "O5Ia" AppMag 7.0 InforURL "http://www.seds.org/messier/xtra/ngc/etacar.html" }
Alternatively, here's a link to a copy of this file that you can download:
ngc3372.3ds
This is the 3D shape model for the picture of the nebula.
Drag this 3DS model to the Celestia subdirectory
extras\Addons\ngc3372\models
Alternatively, here's a link to a copy of this file that you can download:
Note that this model doesn't define a complicated 3D shape for the nebula itself. Instead, it's just a thin rectangular block for holding a photograph of the nebula. To learn how to use "billboards" to display astronomical photographs in Celestia, please see billboard.html.
ngc3372.jpg
This is a JPEG picture of the Nebula.
Drag it to the Celestia subdirectory
extras\Addons\ngc3372\textures\medres\
(All image files used by models must be in the
medres
directory.)
Alternatively, here's a picture of the surface texture image which links to a copy of the texture.
NGC 3372 (241KB)
Note that this surface texture image is an opaque picture of the Nebula and its surrounding stars. Often artists designing deep space models for Celestia remove the stars from the astronomical photographs of the objects. They then provide .STC files specifying the types and locations of many of the stars near the Nebula. The surface textures they provide usually include an Alpha transparency channel, too, which makes the nebulosity translucent. None of these things have been done for this simple example.
Now your directory structure should look something like this:
[return]
(Celestia will prompt with "Target name: " )
NGC 3372[return]
ngc3372.dsc
.)
If the .DSC file is OK, then the name will appear in the upper left corner of Celestia's window along with the distance (8500 ly). You have now "selected" NGC 3372.
c
". Celestia will turn toward the selected object.
That's NGC 3372 in this case. Celestia should pause
briefly while it loads the model and its texture. When the viewpoint
finally stops turning, you should see a purple-red blotch in the middle
of the screen labeled "NGC 3372".
If there's no label, then you did not manage to select the "Label Galaxies" box (or "Label Nebulae"). The "Show Galaxies" box (or "Show Nebulae" box for Celestia v1.4.0 or later) probably isn't selected either. Go back to the "Render" "View Options..." menu and make sure their boxes are checked. You should see the label appear immediately when its box is checked. When you click on [OK], the label will stay while the menu goes away. If you click on [x] at the upper right, the label will go away when the menu does because Celestia will forget the Render changes you just made.
If there is a label but no purple blotch, then you may not have selected either "Show Galaxies" (type a "u" a couple of times to toggle "Show Galaxies") or "Show Nebulae" (type a Caret (^) = Shift 6 on U.S. keyboards; you also may have to type a "space" on keyboards that support diacritical marks as "dead keys", as most European keyboards do.) Alternatively, perhaps Celestia can't find the model or its surface texture image.
Please look at Section 6 for a list of some of the most common problems and possible solutions.
g
". Celestia will take you to a position near the
nebula.
Here's a snapshot taken by Celestia of this nebula.
Earth in NGC 3372
|
and here's a Cel://URL to take you to this viewpoint:
|
Again, I'll assume you're using some version of Windows.
If you've ever downloaded and installed other software, I'm sure this description will be full of things you already know how to do.
These instructions are specifically for the Rosetta Nebula that Rassilon created. You should be able to use a similar procedure for equivalent creations.
Essentially, the steps are:
4.1: Download the Zip archive file containing the addon you want
4.2: Create the directory tree to contain the Addon.
4.3: Copy the Addon files from the zip archive to the
appropriate Celestia directories
4.4: Start Celestia and view the object.
In detail:
Rassilon's downloads are available in the Wayback archive in the directory http://www.shatters.net/~rassilon/. The Rosetta Nebula Addon is at http://www.shatters.net/~rassilon/NGC2237.zip or you can browse the Web directory page to select it. It's over 600KB, so be patient.
extras
directory
which has the name Addons
.
This will let you move all of your Addons at once by moving just
this one directory.
Addons
directory, create a directory for
each Addon when you install it. For example, you might create the
NGC2237
directory.
NGC2237
directory, you must create the directories for
its models and its surface textures: create the directories
models
and textures
Within the
textures
directory, create the directory
medres
.
(The lores
and hires
directories aren't needed
for this particular Addon.)
When you've created the new directories, your directory structure might look something like this:
You need to have a ZIP program installed to extract the files. (Windows XP, Vista and 7 come with one built in.)
\extras\
.
Drag it to the Celestia subdirectory
extras\Addons\NGC2237\
not to a directory named
\extras\
.
###################### # ngc2237.dsc ###################### Nebula "NGC2237" { Mesh "NGC2237.3ds" RA 6.5383 Dec 5.05 Distance 5500 Radius 75 } ######################
Alternatively, here's a link to a copy of this file that you can download:
NGC2244.stc
and NGC2244-2.stc
in the \extras\
folder.
These are "STar Catalogs". They define a cluster of stars in the
middle of the nebula.
Drag them to the Celestia subdirectory
extras\Addons\NGC2237\
, not to a directory named
\extras\
.
(All Catalog files for a specific Addon go into the same "root" directory)
NGC2237.3DS
It's in a directory named \models\
.
This is the 3D shape model for the nebula.
Drag it to the Celestia subdirectory
extras\Addons\NGC2237\models\
rosetta.png
This is a PNG picture that is used to provide surface coloration
for the model. It determines the colors and the transparency of the
various regions of the nebula.
Drag it to the Celestia subdirectory
extras\Addons\NGC2237\textures\medres\
(All image files used by models must be in the
medres
directory.)
Note for Linux users: the .3DS model file specifies ROSETTA.PNG
,
spelled with all upper case letters. The image file that's provided is
spelled rosetta.png
, with all lower case letters.
Those names aren't the same.
You must rename the image file to have all upper case letters
so that Celestia can find it.
Now your directory structure should look something like this:
Note: NGC2237.ZIP
includes an \extras\
directory
which contains all of its catalog files. Those files all must be moved into
the Addons directory itself, \NGC2237\
, and the
folder \NGC2237\extras\
should be deleted.
This is an older Addon which was created before the new directory
layout became possible.
Note to Windows and MacOS users:
When you create an Addon, Please make sure that the names of textures and models agree exactly with the names you use in their Texture and Mesh declarations. If a letter is upper cased in the declaration, make sure it's upper cased in the name of the file itself.
Note to Linux users:
The DSC catalog NGC2237.dsc
above violates this. It specifies
the Nebula Mesh to have the filename
NGC2237.3ds
. However, the file provided is named
NGC2237.3DS
. Those names are not the same, and
Celestia will not be able to locate the Mesh (model) file.
You must rename the file to be spelled "NGC2237.3ds"
with lower case letters in its filetype so Celestia can find it.
[return]
(Celestia will prompt with "Target name: " )
NGC2237[return]
NGC2237.dsc
.)
If the .DSC file is OK, then the name will appear in the upper left corner of Celestia's window along with the distance (5500.000 ly). You have now "selected" NGC2237.
c
". Celestia will turn toward the selected object.
That's NGC2237 in this case. Celestia should pause
briefly while it loads the model and its texture. When the viewpoint
finally stops turning, you should see a tiny pink blotch in the middle
of the screen labeled "NGC2237".
If there's no label, then you did not manage to select the "Label Galaxies" box (or "Label Nebulae"). The "Show Galaxies" box (or "Show Nebulae" box for Celestia 1.4.0 or later) probably isn't selected either. Go back to the "Render" "View Options..." menu and make sure their boxes are checked. You should see the label appear immediately when its box is checked. When you click on [OK], the label will stay while the menu goes away. If you click on [x] at the upper right, the label will go away when the menu does because Celestia will forget the Render changes you just made.
If there is a label but no pink blotch, then you may not have selected either "Show Galaxies" (type a "u" a couple of times to toggle "Show Galaxies") or "Show Nebulae" (type a Caret (^) = Shift 6 on U.S. keyboards; you also may have to type a "space" on keyboards that support diacritical marks as "dead keys", as most European keyboards do.)
Please look at Section 6 for a list of some of the most common problems and possible solutions.
g
". Celestia will take you to a position near the
nebula.
Here's a snapshot taken by Celestia of this nebula.
The constellation of Orion is to the lower right. NGC 2237 as seen from Io |
and here's a Cel://URL to take you to this viewpoint:
|
After you've used this URL to see where the nebula is on the sky, one thing you can do is to hold down the "," (comma) key to increase the magnification of Celestia's "telescope". You can turn it up until the nebula fills the screen!
Many of Rassilon's creations are available on the WayBack Archive site at http://www.shatters.net/~rassilon/. This particular Addon is available at http://www.shatters.net/~rassilon/NGC2244-systems_i.zip. This Zip archive is about 6.5 MB, so it will take a while to download. NGC 2244 is the designation for the Open Cluster of stars in the middle of the Rosette Nebula. The Nebula itself is NGC 2237.
This Addon was designed assuming that you already have installed the Addon described in section 4 above as well as a "Globular Cluster" generator. Installing this Addon by itself has some potential problems which can be used to illustrate how Celestia supports Addons.
Katalina is Rassilon's name for an imaginary star which is the primary content of this Addon. This star name needs to be made known to Celestia. Briefly, the following steps will make that happen:
\extras\Addons\NGC2244\
(This makes it easy to keep track of NGC2244's pieces.)
\extras\Addons\NGC2244\katalina.stc
.
(This tells Celestia where to draw the star.)
NGC2244-katalina.ssc
from the Zip file
to the folder
\extras\Addons\NGC2244\
(This describes all the planets
around the star.)
\textures\medres\
to
\extras\Addons\NGC2244\textures\medres\
.
I'm going to assume you have Celestia v1.3.1 or later.
Editing starnames.dat
is no longer necessary, but you do
have to define Katalina in an STC catalog file. See step
5.3 below.
First some background:
Rassilon defined the planets that orbit around Katalina in
the file NGC2244-katalina.ssc
, and he used the star name
"Katalina" everywhere in that file. So that name has to be
taught to Celestia.
Celestia uses "Hipparcos numbers" to keep track of stars. Hipparcos numbers are numbers assigned by the astronomers who used the Hipparcos Satellite to measure the distances to many stars.
Imaginary stars like Katalina have to be given fake Hipparcos numbers in Celestia. Usually people use numbers between 300000 and 600000.
In order for Celestia to know which star number has which name, both its number and its name have to be included in the STar Catalog (.stc) file used to define the star.
Ignore Rassilon's description in the README in the Zip file,
which says to add a line to the very end of
\data\starnames.dat
. Those instructions are for old
versions of Celestia, before V1.3.1.
extras
directory
which has the name Addons
.
This will let you move all of your Addons at once by moving just
this one directory.
Addons
directory, create a directory for
each Addon when you install it. For example, you might create the
NGC2244
directory.
NGC2244
directory, you must create the directories for
its models and its surface textures: create the directories
models
and textures
Within the
textures
directory, create the directory
medres
.
(The lores
and hires
directories aren't needed for
this particular Addon.)
When you've created the new directories, your directory structure might look something like this:
In order for Celestia to draw a star, you need an .STC (STar Catalog) file that tells Celestia where that star is and what it looks like.
Rassilon buried the definition for the star 500506 in the middle of one of his very big star catalogs. The Readme says you can delete those catalogs if you don't have his Globular Cluster Addon. But if you do that, you can't find Katalina.
Here's a simple .STC file that defines just the star that is
named Katalina. Create this file in the directory
\extras\Addons\NGC2244\
.
You can use your favorite text editor to create it. Notepad is fine.
Wordpad is OK, too.
Do not use a word processing program like
Microsoft Office Word or
OpenOffice Writer. They insert binary document formatting commands which
Celestia does not understand.
####################### #katalina.stc ####################### # HIP 500506 500506 "Katalina" { RA 98.02484576 Dec 5.04107509 Distance 5500.3959 SpectralType "G0Ia-O" AppMag 15.00 } #######################
[back to Contents]
NGC2244-katalina.ssc
\extras\Addons\NGC2244\
(This describes all the planets
around the star.)
Note: NGC2244-systems_i.ZIP
includes an \extras\
directory
which contains all of its catalog files. Those files all must be moved into
the Addons directory itself, \NGC2244\
, and the
folder \NGC2244\extras\
should be deleted.
This is an older Addon which was created before the new directory
layout became possible. If you leave the catalogs in the
extras
folder, Celestia will not be able to
find the textures needed to draw
the planets properly. Instead, they'll look like blank white balls.
[back to Contents]
\textures\medres\
to
\extras\Addons\NGC2244\textures\medres\
.
Once you've
created katalina.stc
,
and put the other files in the right directories,
your directory structure should look something
like this:
[back to Contents]
[return]
katalina[return]
c
g
to visit Rassilon's Katalina system in the heart of the Rosetta Nebula.
Here's a snapshot taken by Celestia of the Katalina solar system.
The Katalina solar system. | and here's a Cel://URL to take you to this viewpoint: |
The first thing to do when you are having problems with Addon objects is to turn on Celestia's "Console Log". To do this, type the keyboard command "~" This is the "tilde" character, Shift-`. On European keyboards, you usually have to follow it by a space. Use the Arrow keys to scroll the log up and down. (Type a tilde again to turn off the display of the log file.)
If the error messages in the log don't help, here are some of the most common problems I've seen:
This should turn the Nebula picture on and off again. The Nebula and Celestia's grey galaxy blobs will always be visible at the same time. If you can't see the grey galaxy blobs, you won't be able to see any Nebulae, either.
This should turn the Nebula picture on and off again. This only affects Nebulae. If you have a European keyboard or one that supports "dead keys" for diacritical marks, you may have to type on the "space bar" after you type each caret.
"[" will turn it down again. The Limiting Magnitude has to be 2.0 or more for Nebula pictures and galaxies to be drawn.
\extras\
folder,
This confuses Celestia, and makes it look for the models and textures
in folders that don't exist, under the \extras\
folder.
\extras\
folder into the
Addon's main folder.
For example, all of the files that are in
\NGC2237\extras\
must be moved into \NGC2237\
itself.
Then delete the now-empty \NGC2237\extras\
folder.
Old versions of Celestia, those before v1.3.0,
required that Addons put their files in among the files
that come with Celestia. The Zip file of one of these older Addons
contains an \extras\
folder which corresponds to
Celestia's own
\extras\
folder. It contains the Addon's catalogs.
Celestia v1.3.0 and later is confused by this and will look
in the wrong place for the models and surface texture images.
Typographical errors are annoying. I don't know how many
times I've stared at a file or directory name and not noticed that
it's speled wrong.
My hand-eye coordination isn't the best. I often manage to drag them into a folder that's nearby, but not the right one.
\medres\
folder.
The surface texture image files specified internally by 3D models
must be in the directory \medres\
The surface texture image files specified by a "Texture" directive
in an SSC catalog can be in any of \hires\
, \lores\
or \medres\
.
mytexture.jpg
, not
MyTexture.Jpg
Windows ignores the case of letters in file specifications. Unix and Linux distinguish between upper and lower case. Addons created on Windows systems often specify names with a different case in the models or catalog files than actually are used for the image files themselves.
If you have a binary file editor like HexEdit, you might try editing the 3D file to find out exactly what texture it's looking for. You could try changing it to use another texture to find out if the problem is related to the image file.
It's safest to change the name of the surface texture image file(s) to be exactly the same as is specified in the 3D model. It's essentially impossible to fix a damaged 3D model, but easy to rename a file.
Check the dimensions of the surface texture image: both sides must be a power of two. e.g. 2048x2048 or 1024x512.
(This is a problem for textures used in Ring definitions,
for moving cloud textures and for textures used for 3D
models.
This is a problem for all 3D models except for
Celestia's built-in spherical objects. For those spheres, Celestia will cut
large textures into pieces that will fit into your card's buffer.)
Solution:
Recreate the texture or scale it to a smaller size that does fit.
First, check the size of your card's texture buffer.
Then check the dimensions of the surface texture image.
If your 3D graphics card has limited memory then you have to be careful not to look at many other objects before trying to look at a new one. Celestia does not flush "old" images from the memory on the card. If there's no room, the surface texture pictures for the new objects won't be loaded. As a result, surface textures don't get drawn properly.
Any open window uses graphics memory. Some image display programs allocate most or all of the available graphics memory to buffer images. Windows 7's Photo Viewer is particularly bad in this regard.
The lores
surface textures only need about half as much graphics memory.
One way this can be done is to rename the folder
\Celestia\textures\medres\
to be
\Celestia\textures\nomedres\
.
You don't have to delete them; just move them to a folder that Celestia
doesn't use. I keep mine in a folder named \holding\
.
The surface normal vectors specify the directions from which the surface is visible and also determine how each facet gets shaded by light sources. If its normal points away from the observer, Celestia will not draw that facet. Some 3D display programs draw all of the facets no matter what directions their vectors point.
Cause: The Addon was designed on a system with a 24 bit or 32 bit Z buffer. Your card's Z buffer is smaller and cannot handle the large range of distances defined in the object.
Solution: Purchase a modern graphics card, e.g. an Nvidia FX5200 or better.
Workaround: Edit the object's DSC catalog file. Reduce the exponent on the "Radius" value to 5. e.g. 1.3e10 should be changed to be 1.3e5.
Cause: Celestia can't allocate any graphics memory.
Solution: Close all unnecessary programs and image viewers.
Any open window uses graphics memory. Some image display programs allocate most or all of the available graphics memory to buffer images. Windows 7's Photo Viewer is particularly bad in this regard.
For a pictorial, step-by-step description of how to install Celestia under Windows, please take a look at http://www.lepp.cornell.edu/~seb/celestia/novice-panorama.html. It includes a description of how to install wrap-around panorama images, too.
If you're running Windows, download the .EXE file of the installer for the version of Celestia that you want. Then run it. That starts the installation program. The installation software will let you put Celestia anywhere you want. It's usually a bad idea to put it in the same directory where you have a previous verison of Celestia. I rename the old directory so it has the version of Celestia at the end: e.g. Celestia130. I then install the new version of Celestia into a directory named just Celestia.
After it has created the directories and copied the program files, the Windows installation script asks you to chose a few more options. Be sure to select "desktop icon", "associate URLs" and "associate .CEL scripts." (I might have the names slightly wrong. This is from memory.)
Note that whenever you run a Celestia installation program, it will change the icon, URL and CEL associations to point to the location of the copy of the program that it just installed. If you've installed the program into a new folder, you can still run the old program by going to its folder and clicking directly on its icon. Under Windows, you also can use the right-mouse-button to drag a shortcut of the old icon to your desktop if you want.
Some Addons might have requred changes to files that get overwritten by
the new install, like solarsys.ssc
or
celestia.cfg
. Installing a new
version of Celestia on top of the old one will damage those Addons.
I've found it works best to rename Celestia's current directory to be
something else and then install the new version. On a Windows system,
for example, you can rename Program
Files\Celestia\
to be Program Files\Celestia131\
and then let the
installation program recreate a new copy of
Program Files\Celestia\
.
That way you can still run the previous version when you want and your
existing Addons can be moved to the new version at your convenience.
If you're running Linux, there are several Celestia kits designed for particular SuSE and Mandrake versions. Otherwise, you'll have to find a version of Celestia elsewhere or build Celestia yourself from scratch.
There also is a Celestia kit designed for MacOS X, or you can build the program from scratch.
If you don't tell me that something's missing, unclear or wrong, I can't improve it.