# A Quick Tour of &kstars;

This chapter presents a guided tour of &kstars;, introducing many of its important features.

Here's a screenshot of the &kstars; main window:
Main Window

In the above screenshot, you can see the sky display centered on Betelgeuse, the brightest star in the constellation Orion. Orion has just risen above the eastern horizon horizon. Stars are displayed with realistic colors and relative brightnesses. The brightest stars have their names labeled (&eg;, Betelgeuse). M 42, the Orion Nebula, is visible to the right of Orion's belt stars, just above the horizon. If you look closely, you can also see the planet Saturn in the upper left. In three corners of the Sky display, there are on-screen text labels displaying data on the current time (LT: 12:29:51 03/23/03), the current Geographic Location (Baltimore, Maryland, USA), and the current object in the center of the display (Focused on: Betelgeuse (alpha Orionis)). Above the sky display, there are two toolbars. The main toolbar contains shortcuts for menu functions, as well as a time-step widget which controls how fast the simulation clock runs. The view toolbar contains buttons that toggle the display of different kinds of objects in the sky. At the bottom of the window, there is a status bar which displays the name of any object you click on, and the sky coordinates (Right Ascension and Declination) of the mouse cursor.

## Where am I?

The first thing to do is to set the geographic location. By default, &kstars; assumes you are in Greenwich, UK (home of the Royal Observatory, where longitude=0 is defined). Since you are probably somewhere else, you'll want to change this.

Open the Set Geographic Location window by selecting Set Geographic Location... from the Settings menu, or by pressing the Globe icon in the toolbar, or by typing &Ctrl;g.

Here is a screenshot of the Set Geographic Location window: Changing the Geographic Location Set Location Window

There is a list of over 2500 predefined cities available to choose from. You set your location by highlighting a city from this list. Each city is represented in the world map as a small dot, and when a city is highlighted in the list, a red crosshairs appears on its location in the map.

It isn't practical to scroll through the full list of 2500 locations, looking for a specific city. To make searches easier, the list can be filtered by entering text in the boxes below the map. For example, in the screenshot, the text Ba appears in the City Filter box, while M has been entered in the Province Filter box, and USA is in the Country Filter box. Note that all of the cities displayed in the list have city, province, and country names that begin with the entered filter strings, and that the message below the filter boxes indicates that 7 cities are matched by the filters. Also notice that the dots representing these seven cities in the map have been colored white, while the unmatched cities remain gray.

The list can also be filtered by location in the map. Clicking anywhere in the world map will show only those cities within two degrees of the clicked location. At this time, you can search by name, or by location, but not both at once. In other words, when you click on the map, the name filters are ignored, and vice versa.

The longitude, latitude and time zone information for the currently-selected location are displayed in the boxes at the bottom of the window. If you feel that any of these values are inaccurate, you can modify them and press the Add to List button to record your custom version of the location. You can also define a completely new location by pressing the Clear Fields button, and entering the data for the new location. Note that all fields except the optional State/Province must be filled before the new location can be added to the list. &kstars; will automatically load your custom locations for all future sessions. Please note, at this point, the only way to remove a custom location is to remove the appropriate line from the file `~/.kde/share/apps/kstars/mycities.dat`.

If you add custom locations (or modify existing ones), please send us your `mycities.dat` file so that we can add your locations to the master list.

## What Time Is It?

The next thing you may want to do is change the time and/or date. When &kstars; starts up, the time is set to your computer's system clock, and the &kstars; clock is running to keep up with the real time. If you want to stop the clock, select Stop Clock from the Time menu, or simply click on the Pause icon in the toolbar. You can make the clock run slower or faster than normal, or even make it run backward, using the time-step spinbox in the toolbar. This spinbox has two sets of up/down buttons. The first one will step through all 83 available time steps, one by one. The second one will skip to the next higher (or lower) unit of time, which allows you to make large timestep changes more quickly.

You can change to any time or date by selecting Set Time... from the Time menu, or by pressing the time icon in the toolbar. The Set Time window uses a standard &kde; Date Picker widget, coupled with three spinboxes for setting the hours, minutes and seconds. If you ever need to reset the clock back to the current time, just select Set Time to Now from the Time menu.

The current version of &kstars; cannot accept dates before October 1, 1752, nor dates after the year 8000. These are limitations of the &Qt; Date/Time class. We plan to implement our own date/time class in a future version, which will allow for more remote dates.

## Have a Look Around!

Now that we have the time and location set, let's have a look around. You can pan the display using the arrow keys. If you hold down the &Shift; key before panning, the scrolling speed is doubled. The display can also be panned by clicking and dragging with the mouse. Note that while the display is scrolling, not all objects are displayed. This is done to cut down on the CPU load of recomputing object positions, which makes the scrolling smoother (you can configure what gets hidden while scrolling in the Display Options window).

There are seven ways to change the magnification (or Zoom level) of the display:

1. Use the + and - keys

2. Press the zoom in/out buttons in the toolbar

3. Select Zoom In/Zoom Out from the View menu

4. Select Zoom to Angular Size... from the View menu. This allows you to specify the the field-of-view angle for the display, in degrees.

5. Use the scroll wheel on your mouse

6. Drag the mouse up and down with the &MMB; pressed.

7. Hold down &Ctrl; while dragging the mouse. This will allow you to define a rectangle in the map. When you release the mouse button, the display will zoom to match the rectangle.

Notice that as you zoom in, you can see fainter stars than at lower zoom settings.

Zoom out until you can see a green curve; this represents your local horizon. If you haven't adjusted the default &kstars; configuration, the display will be solid green below the horizon, representing the solid ground of the Earth. There is also a white curve, which represents the celestial equator, and a tan curve, which represents the Ecliptic, the path that the Sun appears to follow across the sky over the course of a year. The Sun is always found somewhere along the Ecliptic, and the planets are never far from it.

## Objects in the Sky

&kstars; displays thousands of celestial objects: stars, planets, comets, asteroids, clusters, nebulae and galaxies. By default, stars are drawn as white circles with a colored border that simulates the star's real color. Planets are drawn as colored dots at low zoom levels, but as an actual image of the planet as you zoom in. Deep-sky objects (clusters, nebulae and galaxies) are drawn with symbols color-coded to indicate the catalog to which they belong (Messier, NGC or IC). Most Messier objects are drawn as real images on the map at higher zoom levels. Deep-sky objects with extra image or information links available are drawn with a special color (red by default). Clicking on an object will identify it in the status bar. Double clicking will recenter the display on the object and begin tracking the object (so that it will remain centered as time passes). Right clicking an object opens a popup menu with more options.

### The Popup Menu

Here is an example of the right click popup menu, for the Orion Nebula:

Popup Menu for M 42
Popup Menu for M 42

The appearance of the popup menu depends somewhat on the kind of object you right click on, but the basic structure is listed below. You can get more detailed information about the popup menu.

The top section contains information labels (which are not selectable). The top one to three labels display the object's name(s) and object type. The next three labels show the object's rise, transit, and set times.

The middle section contains items for performing actions on the object, such as Center and Track, Details... (which opens the object's Detailed Information Dialog), Add Label, and Add/Remove Trail (only for Solar System bodies).

The bottom section contains links to images and/or informative webpages about the selected object. If you know of an additional &URL; with information or an image of the object, you can add a custom link to the object's popup menu using the Add Link... item.

### Finding Objects

You can search for named objects using the Find Object window, which can be opened by clicking on the search icon in the toolbar, by selecting Find Object... from the Focus menu, or by pressing &Ctrl;F. The Find Object window is shown below:

Find Object Window Find Object Window

The window contains a list of all the named objects that &kstars; is aware of. Many of the objects only have a numeric catalog name (for example, NGC 3077), but some objects have a common name as well (for example, Whirlpool Galaxy). You can filter the list by name and by object type. To filter by name, enter a string in the edit box at the top of the window; the list will then only contain names which start with that string. To filter by type, select a type from the combo box at the bottom of the window.

Highlight the desired object in the list, and press Ok. The display will center on the object. Note that if the object is below the horizon, the program will warn you that you may not see anything except the ground (you can make the ground invisible in the Display Options window, or by pressing the Ground button in the View toolbar).

&kstars; will automatically begin tracking on an object whenever one is centered in the display, either by using the Find Object window, by double-clicking on it, or by selecting Center and Track from its right-click popup menu. You can disengage tracking by panning the display, pressing the Lock icon in the Main toolbar, or selecting Track Object from the Focus menu.

## Customizing the Display

There are several ways to modify the display to your liking.

- Select a different color scheme in the Settings Color Schemes menu. There are four predefined color schemes, and you can define your own in the View Options window.

- Toggle whether the Toolbars are drawn in the Settings Toolbars menu. Like most KDE toolbars, they can also be dragged around and anchored on any window edge, or even detached from the window completely.

- Toggle whether the Info Boxes are drawn in the Settings Info Boxes menu. In addition, you can manipulate the three Info Boxes with the mouse. Each box has additional lines of data that are hidden by default. You can toggle whether these additional lines are visible by double-clicking a box to shade it. Also, you can reposition a box by dragging it with the mouse. When a box hits a window edge, it will stick to the edge when the window is resized.

- Choose an FOV Symbol using the Settings FOV Symbols menu. FOV is an acronym for field-of-view. An FOV symbol is drawn at the center of the window to indicate where the display is pointing. Different symbols have different angular sizes; you can use a symbol to show what the view through a particular telescope would look like. For example, if you choose the 7x35 Binoculars FOV symbol, then a circle is drawn on the display that is 9.2 degrees in diameter; this is the field-of-view for 7x35 binoculars.

  You can define your own FOV symbols (or modify the existing symbols) using the Edit FOV Symbols... menu item, which launches the FOV Editor:

  Field-of-View Symbols Editor
  FOV Symbol Editor

  The list of defined FOV symbols is displayed on the left. On the right are buttons for adding a new symbol, editing the highlighted symbol's properties, and removing the highlighted symbol from the list. Note that you can even modify or remove the four predefined symbols (if you remove all symbols, the four defaults will be restored the next time you start &kstars;). Below these three buttons is a graphical preview display showing the highlighted symbol from the list. When the New... or Edit... button is pressed, the New FOV Symbol window is opened:

  New Field-of-View Symbol
  New FOV Symbol

  This window lets you modify the four properties that define a FOV symbol: name, size, shape, and color. The angular size for the symbol can either be entered directly in the Field of View edit box, or you can use the Eyepiece/Camera Tabs to calculate the field-of-view angle, given parameters of your telescope/eyepiece or telescope/camera setup. The four available shapes are: Circle, Square, Crosshairs, and Bullseye. Once you have specified all four parameters, press Ok, and the symbol will appear in the list of defined symbols. It will also be available from the Settings | FOV menu.

In addition to these options in the Settings menu, there are a large number of customization options available in the View Options window, which is covered in detail in the next chapter.