# Configuring &kstars;

## Setting the Geographic Location

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

There is a list of over 3400 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 is not practical to scroll through the full list of 3400 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 `A` appears in the City filter: box, while `Te` 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 6 cities are matched by the filters. Also notice that the dots representing these six 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 City) 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 Province:/Country: 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 `kstars/mycities.dat` in your folder ``qtpaths` `--paths GenericDataLocation`` .

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.

## Setting the Time

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 the Time Stop Clock menu item, or simply click on the Stop Clock 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 set the time and date by selecting the Time Set Time... menu item, or by pressing the Time icon in the toolbar. The Set Time window uses a standard &kde; Date Picker widget, coupled with a spinbox for setting the hours and minutes. If you want to re-synchronize the simulation clock back to the current CPU time, just select the Time Set Time to Now menu item.

&kstars; can accept very remote dates beyond the usual limits imposed by QDate. Currently, you can set the date between the years -100000 and +100000. We may extend this range even further in future releases. However, please be aware that the accuracy of the simulation becomes more and more degraded as more remote dates are examined. This is especially true for the positions of solar system bodies.

## The Configure &kstars; Window

The Configure - &kstars; window allows you to modify a wide range of display options. You can access the window with the Configure toolbar icon, or by selecting the Settings Configure &kstars;... menu item. The window is depicted below: Configure - &kstars; Window Configure - &kstars; Window

The Configure - &kstars; window is divided into fourteen pages: Catalogs, Solar System, Satellites, Supernovae, Guides, Terrain, Image Overlays, Colors, FITS, INDI, Ekos, Xplanet, Advanced and Developer.

In the Catalogs page, you determine several properties concerning the display of the star and deep sky object catalogs.

In the Solar System page, you can specify whether the Sun, Moon, planets, comets and asteroids are displayed.

The Satellites page allows you to set the satellites view options.

The Supernovae page allows you to manage how supernovae are displayed by &kstars;.

The Guides page lets you toggle whether non-objects are displayed (&ie;, constellation lines, constellation names, the Milky Way contour).

- It is possible to choose a Sky culture: for the constellation lines and names on this page. The current version of &kstars; includes data for more than a dozen sky cultures.

The Terrain page allows you to set the terrain or landscape image and configure its speedup options.

The Image Overlays page allows you to add and manage your own images that will be displayed in the skymap.

The Colors page allows you to set the color scheme, and to define new custom color schemes.

For detailed explanation of the options on the FITS page see the Configure FITS section.

For detailed explanation of the options on the INDI page see the Configure INDI section.

For detailed explanation of Ekos astrophotography suite, see the Ekos section of this manual.

The Xplanet page provides fine-grained control over Solar system planet surface renderer Xplanet (should be installed separately).

The Advanced page provides fine-grained control over the more subtle behaviors of &kstars;.

The Developer page allows you to enable or disable a few options mostly useful for developers or for folks looking to help debug issues. Currently these are enabling the saving of images during Ekos's autofocus, guiding and alignment.

## Catalogs

Catalogs Window Catalogs Window

In the Catalogs page, you can configure which object catalogs are displayed by &kstars;, as well as how much information you would like to be included on the Sky Map. By default, &kstars; includes ~300,000 named and unnamed stars up to magnitude 8. For Deep Sky Objects, the included catalog is the New General Catalog (NGC) including the Index Catalog (IC) and the Messier Catalog.

The New General Catalog of Nebulae and Clusters of Stars (abbreviated as NGC) is a catalog of ca 7,840 deep-sky objects.

The Index Catalog of Nebulae and Clusters of Stars (abbreviated as IC) serves as a supplement to the NGC, and contains an additional 5,386 objects, collectively known as the IC objects.

You can install new catalogs using &kstars; Add-On Installer. You can open it via the Data Download New Data... menu item. You can choose from a list of catalogs, including (but not limited to):

- Steinicke NGC/IC Catalog: is a more complete NGC/IC catalog.

- Abell Planetary Nebulae Catalog: is a catalog of 86 planetary nebulae. The maximum magnitude is represented by Abell 47's value of 19.5.

- Sharpless HII region Catalog: is the Sharpless (Sh2) catalog of HII regions (diffuse nebulae).

- Hickson Compact Groups: is a catalog consisting of 99 compact groups of galaxies.

- Tycho-2 Star Catalog: is a catalog of more than 2.5 million of the brightest stars. It contains stars with a magnitude value from 8.0 to 12.5.

- USNO NOMAD Catalog: is a catalog of about 100 million stars with magnitude from 12.5 to 16.5. Note that is requires Tycho-2 to be installed.

The following is a summary of catalogs in &kstars;:

## Stars Catalogs

Name | Abbreviation | Number of objects | Magnitude | Add-On | Default
Default Catalog | Default | ~300,000 | Up to 8 magnitude | No | Yes
Tycho-2 | Tycho2 | more than 2.5 million | 8.0-12.5 | Yes | No
Naval Observatory Merged Astronomic Dataset | USNO NOMAD | 100 million | 12.5-16.5 | Yes | No

## Deep-sky objects Catalogs

Name | Abbreviation | Number of objects | Magnitude | Add-On | Default
New General Catalog of Nebulae and Clusters of Stars (OpenNGC) | NGC | 7,840 | - | No | Yes
Steinicke NGC/IC | - | - | - | Yes | No
Abell Planetary Nebulae Catalog | - | 86 | Up to 19.5 magnitude | Yes | No
Sharpless HII region Catalog | Sh2 | - | - | Yes | No
Hickson Compact Groups | - | 99 | - | Yes | No

A potentially more up-to-date listing can be found in the catalog repository documentation.

The Stars section allows you to manage how stars are displayed in &kstars;. You can choose to see the stars or not by checking the Star catalogs checkbox. If you check it, then multiple options will be enabled. Thus, you can set how many stars are drawn on the map using the Star density: slider. You can also customize &kstars; to toggle star name and magnitudes. Star names are drawn next to bright stars. To display labels of fainter stars, increase the Label density: slider.

Below the stars section, the Deep-Sky Objects section controls the display of several non-stellar object catalogs. You can toggle the display of Deep Sky Objects and control the display of their names and magnitudes. By default, the list of deep-sky objects includes the Messier, NGC and IC catalogs. Addons catalogs are available via the Data Download New Data... menu item where you can download catalogs provided by &kstars; team and the community through the catalog packaging repository. The DSO minimal zoom: slider controls the minimal zoom level for which the DSOs are shown. Increasing the minimal zoom level can lead to performance improvements when panning the skymap zoomed-out. The DSO cache percentage: slider regulates how much of the DSO master catalog is being kept in memory. If you experience memory issues with large catalogs, try lowering the percentage. The Label density: slider controls the perceived density of labels for the DSOs. If labels start to overlap and the skymap begins to look too crowded, try tuning this option. The Faint limit zoomed in/out: regulates up to which magnitude objects are shown on the skymap (higher magnitude is fainter). If Show objects of unknown magnitude is ticked, objects of unknown magnitude are always shown.

The following sections will detail how DSO catalogs work in &kstars; and how they're managed.

### The DSO Catalog Database

This section aims at introducing the catalog database of &kstars; in simple but technical terms. It can be skipped without missing anything essential but helps understanding how to deal with and create (custom) catalogs.

DSO catalogs in &kstars; are just SQL (sqlite3) database tables. Each catalog is represented by its own table which contains all its objects and an entry in a catalog metadata table. Additionally, catalogs may be imported or exported from and into stand-alone database files.

Each object has the usual properties like name and coordinates but additionally features two IDs. The first ID is the unique identifier for the specific object and is calculated by hashing all the object fields along with the catalog id. Because objects can be contained in several catalogs each object has an additional object id (OID) that identifies the physical object and may be shared by several objects of different catalogs.

To speed up object lookup all enabled catalogs are merged into a master table. Each catalog has a priority number and if several objects with the same OID occur the one from the catalog with the highest priority is loaded. The objects from the master catalog are then drawn on the sky and generally available in &kstars;.

Currently, deduplication (the assignment of OIDs) is only supported by the tooling of the catalog packaging repository. The aim of this tool-chain is to reproducibly build catalogs in a homogeneous environment. Every catalog is implemented as a python module and provides standard methods to acquire data, parse it and find duplicates in other catalogs. All downloadable catalogs are implemented this way. If you'd like to make a catalog of your own available for &kstars;, it is recommended that you implement it as a package in the repository. The tooling provided there is so flexible, that it should work for you. For more information on how to do that see the catalog repository documentation. If you are not familiar with python programming you can request the addition of a catalog by opening a ticket in the repository or contacting the maintainers. &kstars; provides also provides means to create custom catalogs by manually entering data or importing CSV tables, but those are less flexible and offer no deduplication.

### The Catalog Management &GUI;

The catalog management &GUI; is reached via the Data Manage DSO Catalogs... menu item and is displayed below. DSO Manager The DSO catalog management interface.

The DSO catalog management interface.

On the left, a list of catalogs is displayed. In this list, you can read off key catalog properties, including whether a catalog is enabled, what its ID is and what its name is. The Mutable column signifies whether the catalog can be edited or not. Catalogs which have been downloaded from the catalog repository via the Data Download New Data... menu item are usually immutable whereas user-created catalogs aren't. You can always Clone a catalog to make it mutable.

The buttons in the upper right corner allow you to add catalogs to the database.

Import Catalog...

- Import a catalog in the `.kscat` format from a file.

  This is usually done to try out new versions of catalogs that haven't yet been picked up by the usual download server.

With the buttons in the lower right corner, you can add, remove, modify and explore catalogs. Their actions always refer to the currently selected catalog (the highlighted row on the left).

Create Catalog...

- Create a new catalog. See create_catalog.

Enable / Disable

- Enable or disable a catalog.

  This is reflected in the skymap upon closing the catalog management &GUI;.

Remove

- Remove a catalog from the catalog database.

  This is reflected in the skymap upon closing the catalog management &GUI;.

Export...

- Export a catalog into a `.kscat` file.

  The resulting file can be imported with Import Catalog... button.

Clone...

- Make an exact copy of the catalog and insert it into the database.

  This is useful if you wish to make modifications to an immutable catalog.

  Note however that this is not the recommended way to alter catalogs that are provided by the catalog packaging repository &ie; the catalogs downloaded via the Data Download New Data... menu item.

Colors

- Open the catalog color editor (See catalog_colors.).

  This will open a dialog which allows you to set the colors in which objects from the selected catalog will be displayed for each color scheme.

More...

- Open the catalog details dialog. (See catalog_details.)

  In there, you can see the contents of the catalog, as well as some more meta information. Amongst other things, you can also edit its contents (if it is mutable).

### Creating a new Catalog

Catalog creation dialog Catalog creation dialog.

This dialog reached through the catalog management &GUI; (see catalog_gui). The ID: field will be automatically chosen but can be changed. The Color: field configures in which color the objects of the catalog will be displayed. All the other values are optional or have sensible defaults. You can, of course, change these values at a later point.

Upon clicking Ok an empty catalog with the meta data entered into the dialog will be added to the database and can then be filled with objects. (See catalog_details and csv_import.)

### Catalog Color Editor

Catalog color editor The catalog color editor.

This dialog reached through the catalog management &GUI; (see catalog_gui). Each button represents the color that objects will be drawn in for a specific color scheme. Clicking on a button will allow you to choose a color with a color picker. The button colors are initialized with the default colors from the catalog specification. The color "default" is the color which will be chosen for the catalog if there is no color set for a color scheme.

### Catalog Details Dialog

Catalog details dialog The catalog details dialog.

This dialog reached through the catalog management &GUI; (see catalog_gui). In the top left corner, the catalog metadata is being displayed. On the right, a table of all objects in the catalog is being shown. The search line above the table filters objects by name. Double-clicking a row opens the object details dialog (see tool-details).

Selecting a row enables the Object menu on the left. Selecting multiple rows performs the single-object action for each selected object.

Edit...

- Edit the catalog object. (See add_object).

Remove

- Removes the object from the catalog.

Below the Object section, the general catalog options are situated.

Edit Catalog Meta...

- Edit the catalog metadata displayed in the top left. This opens the dialog described in create_catalog.

Add Object...

- Add an object to the catalog. (See add_object.)

Import CSV...

- Import objects from a tabular text format (csv, tsv, &etc;) into the catalog. (See csv_import.)

#### Adding/Editing Objects

Add/Edit DSO Dialog Add/Edit DSO Dialog

This dialog allows to create or edit a deep sky object (DSO). The Basics section contains fields that have to be filled in.

Name:

- The name of the object which will be displayed in the sky.

Type:

- The type of the object.

RA / Dec (°, J2000):

- The coordinates of the object in degrees and with respect to the J2000 epoch.

Apparent magnitude:

- The apparent magnitude of the object.

The Optional section contains data fields that are optional, is divided into two subsections. They are set to and can be left at their defaults.

The Size Info in Arcminutes subsection. The object is modeled as an ellipse which is described by its major and minor axis.

The Misc subsection.

Long name:

- A longer, more descriptive name.

  Usually, the long name is something like Andromeda Galaxy for the object M31. It can contain alternative designations and names in other catalogs as well.

Catalog identifier:

- A catalog internal identifier.

  For example the screenshot above, the object originates from the OpenNGC catalog where each row is identified by NGCXXXX.

Flux:

- The flux of the object. Only applies for radio sources.

Position angle (°):

- If the object is extended, it must have some orientation in the sky. The position angle is the angle between its major axis and a straight line to the north pole.

#### Importing CSV (and similar formats)

Importing CSV Catalogs Importing CSV Catalogs

The screenshot above shows the CSV import dialog in its default state. In the Input section, you can configure the csv parser. The Comment prefix: is the character that signals commented-out lines in the input. The Separator: should be adjusted to fit your input. Usually, it is , or ; but other separators can occur. Finally, you can choose to skip a number of lines at the beginning of the file. Select/Read button lets you choose a csv file to read with the above configuration. After that, the dialog will look as in the screenshot below.

Importing CSV Catalogs, Populated Importing CSV Catalogs

In the top right you can choose whether coordinates are being expressed in degrees or hours/minutes/seconds. The Mapping section lets you map columns in the CSV file to data fields in &kstars;. Selecting Ignore assigns the default value for this field. Entering your own text will use this as the value for every object being read. The Type Mapping section maps strings to object types. You can add and remove mappings by clicking + or -. When you're done mapping, you can test your settings by clicking Preview to read the first few objects from the csv. If you are satisfied you can click OK to import the whole catalog or adjust your settings and preview again. As a reference, a mapping for the OpenNGC catalog is shown in the below screenshot.

Importing CSV Catalogs, OpenNGC Importing CSV Catalogs

## Solar System

Solar System Window Solar System Window

In the Solar System page, you can specify whether the Sun, Moon, planets, comets and asteroids are displayed, and whether the major bodies are drawn as colored circles or actual images. You can also toggle whether solar system bodies have name labels attached, and control how many of the comets and asteroids get name labels. There is an option to automatically attach a temporary orbit trail whenever a solar system body is tracked, and another to toggle whether the color of the orbit trail fades into the background sky color.

## Satellites

Satellites Window Satellites Window

The Satellites page allows you to set the satellites view options. Firstly, you can see or hide the satellites on the skymap using Show satellites checkbox from the top View Options section. By default, satellites are drawn as small light red filled circles with an optional dark red name label next to them. You can enable or disable these labels by checking or not the Show labels checkbox. It is located below the Show satellites checkbox, within the View Options section.

The colors of the dots representing satellites and their name labels can be easily customized using the Colors page from the same Configure - &kstars; window. In addition, satellites can be drawn just like regular stars by checking the Draw satellites like stars checkbox. To display only the visible satellites from your current geographic location and time, select Show only visible satellites.

&kstars; can draw artificial satellites from many predefined groups. Thus, you can select to display a particular group, multiple groups or partially select subgroups. Under each group, a list of individual satellites is presented. To select all satellites from a group, you need to check the group checkbox. You can also select only the satellites of interest in each group. The satellites orbital elements can be updated via the internet by pressing the Update TLEs button. Another way for updating the satellites orbital elements is to use the Data Updates Update Satellites Orbital Elements menu item. If you know the name of a desired satellite then you can use the search satellites method that &kstars; provides. You need to enter the name of satellite in the Search satellites text box and the list will be reduced only to its best matches.

You can add new satellites to &kstars; default satellites set by editing the `kstars/data/satellites.dat` file. As each line of this file is a group of satellites, you need to add a new entry for your desired satellites group. An entry should have the following format: `Group Name;local_filename;url`. For example: `Iridium;iridium.tle;https://celestrak.com/NORAD/elements/iridium.txt`.

## Supernovae

Supernovae Window Supernovae Window

The Supernovae page allows you to decide if the supernovae are displayed or not by checking the Show supernovae checkbox. By default, supernovae are drawn as small light orange + mark. As for satellites, the color of supernovae can be easily customized using the Colors page.

You can set the magnitude limit for showing a supernova as well as magnitude limit for supernova alerts using the spin boxes control. The limiting magnitude is the faintest apparent magnitude of an skyobject that is visible with the naked-eye or a telescope.

The list of recent supernovae can be updated via the Data Updates Update Recent Supernovae data menu item.

## Guides

Guides Window Guides Window

The Guides page lets you toggle whether non-objects are displayed (&ie;, constellation lines, constellation names, the Milky Way contour, the celestial equator, the ecliptic, the horizon line, and the opaque ground). You can also choose a sky culture, whether you would like to see Latin constellation names, IAU-standard three-letter abbreviations, or constellation names using your local language.

## Terrain

Terrain Window Terrain Window

The Terrain page lets you configure whether the terrain (landscape) image will be shown on the skymap.

The user is responsible for creating a partially-transparent image, that is overlayed onto the sky map. This image should have transparent regions that the user creates to let the skymap show through, and opaque regions representing the trees, buildings, the landscape around the telescope. There is a particular format required, and this is a significant effort. There are many resources on the web that explain how this is done for Stellarium. The details of image creation are the same.

Initially, the user captures a full sphere equirectangular projection image from approximately the same point-of-view as his/her telescope. This kind of image can be captured with the Google Camera App, or the Google YouTube App on iPhone, or likely many other camera apps. The user then needs to edit the resulting image so that the sky is erased/transparent, and save it as a PNG. Finally, the user needs to determine where North is in the image, so it can eventually be aligned with the skymap. Once all that is done, the sky map can simulate the local sky view including the local terrain.

Once the image is created, it is possible to upload it via the Terrain page and configure the azimuth correction value (in degrees) that allows the user to rotate the view so north in the sky map is aligned with the north in the image.

Moreover, some speedup options can be configured to achieve the best user experience when rendering the terrain on the sky map.

You can toggle the terrain overlay on and off using a keyboard shortcut &Ctrl;&Shift;T and the View Show Terrain menu item.

## Image Overlays

Image Overlays on SkyMap Image Overlays on SkyMap

Image overlays are custom images (typically `.jpg`) that are rendered onto the skymap over stars and other skymap items, but below the terrain. These images are added by you, the user, a sort of personal sky catalog. If configured properly, these personal images can be displayed almost perfectly aligned with other objects in the sky.

Image Overlays Window Image Overlays Window

The Image Overlays page lets you configure whether image overlays will be shown on the skymap, and helps you add them to the system. The image at the start of this section shows the skymap with image overlays enabled and some image overlays loaded.

Each time it starts up, &kstars; looks for new image overlay images in a special directory, parallel to the logs directory, named `imageOverlays`. On Linux this can be found in `~/.local/share/kstars/imageOverlays`. The exact location for your system can be found by clicking the Overlay Directory button near the top of the Image Overlays config page shown at the top of this section. To start, add your images to that directory. Ideally, for performance reasons these aren't massive files, but probably images with widths 1000 or 2000 should be fine. To add additional images in the future, add them to the same directory and click the refresh button or restart &kstars;. To remove overlays, remove them from the directory and click the refresh button or restart &kstars;.

Start &kstars; once you have images in the `imageOverlays` directory. If you then go to the Image Overlays config page, you should see the new files listed in the table. The new images will show their status as Unprocessed. Only images whose status is OK are displayed on the SkyMap. That is because &kstars; needs to know the sky location, size, and orientation for these images before it can display them. To change the status to OK you need to plate-solve the images or add the required information manually--see below.

To prepare your images for display, you need to plate-solve the images (one time only). To do this, find an image in the table, click on its filename, and then click Solve below the table. The Solve button's label should switch to Cancel during the solve, and then when completed successfully, the solved parameters are displayed in the table and the status is changed to OK. A successful plate-solve's information is stored in the user database so that solving doesn't need to be repeated. The solved image should from then on appear in its proper position in the SkyMap. You can plate-solve multiple images in a single operation by clicking on the first image's filename, then holding down the &Shift; key and clicking on another filename. All the image files between the filenames should be selected. Then clicking Solve will attempt to solve them all. However, &kstars; will not attempt to plate-solve images whose status is OK, it will skip those images. (If you wish to re-plate-solve images with status OK, then manually change their status to Unprocessed and click Solve). It is possible that if you select several images, a few of them will not be successfully solved.

Plate solving these images can sometimes be difficult. That is because at this point the system has no information as to the scale or position to look, and thus it is a blind solve. To improve your chance for success, you can enter an approximate RA/DEC center sky position into the RA and DEC columns for the row you are trying to solve. You can also add an image scale, in arcseconds-per-pixel. You can add a default scale to the right of the Solve button in the box labeled Default a-s/px so that all solving attempts use this scale by default. You can also add a scale directly into the table-row-column, which would override the default. You can choose which StellarSolver profile the solver uses (these profiles can be edited in Ekos' Align tab). Finally, you can adjust the solver's Timeout in seconds.

If you have problematic images that won't solve, you can still display them by manually entering the values (that the solver didn't find) into the table. They are the RA, DEC, arcsecond-per-pixel, orientation angle, and east-to-the-right (or West-to-the-right) settings. Once you have done that, you can then change the status to OK and &kstars; will save these values to the user database as if they had been automatically solved.

There are a few more controls on the Image Overlays settings page. The Show image overlays checkbox at the top of the page enables or disables this feature--that is, toggles whether any image overlays are display on the SkyMap or not.

The Maximum image dimension: spinbox allows you to vary the maximum image dimension used for images. That is, if you place images that are, for example, 5000 pixels wide into the `imageOverlays` directory, but this input box's value is 1000, then the 5000-pixel-images will be read in, but then downsampled to 1000-pixels-wide before display. This is done to reduce the memory footprint and cpu usage of this feature. It would be more efficient to add image files with the desired image width.

The Center SkyMap on selection checkbox allows you to easily navigate to the overlay images without directly manipulating the SkyMap. With this enabled, you select a row in the overlay table (&ie;, by clicking on the filename field) and the skymap is moved to that image if the image's status is OK. At that point you can move from one image to the next with &Up; and &Down; arrow keyboard commands.

## Colors

Colors Window Colors Window

The Colors page allows you to set the color scheme, and to define custom color schemes. The tab is split into two panels:

The left panel shows a list of all display items with adjustable colors. Click on any item to bring up a color selection window to adjust its color. Below the list is the Star color mode: dropdown box. By default, &kstars; draws stars with a realistic color tint according to the spectral type of the star. However, you may also choose to draw the stars as solid white, black or red circles. If you are using the realistic star colors, you can set the saturation level of the star colors with the Star color intensity: spinbox.

The right panel lists the defined color schemes. There are four predefined schemes: the Default Colors scheme, Star Chart, which uses black stars on a white background, Night Vision, which uses only shades of red in order to protect dark-adapted vision, and Moonless Night, a more realistic, dark theme. Additionally, you can save the current color settings as a custom scheme by clicking the Save As... button. It will prompt you for a name for the new scheme, and then your scheme will appear in the list in all future &kstars; sessions. To remove a custom scheme, simply highlight it in the list, and press the Remove button.

## FITS

FITS Window FITS Window

FITS (Flexible Image Transport System) is a popular open standard for storage, transmission and processing of digital data. For the details, one is referred to the corresponding Wikipedia article. This page allows you to configure presentation and processing of FITS data in &kstars;.

The left panel is for configuring FITS viewer itself.

Check the Use FITS viewer item if you want automatically display received images in the FITS Viewer.

The Single preview tab item is to display all captured FITS images in a single tab instead of multiple tabs per image. The Single window capture item is to display captured FITS images from all cameras in a single FITS Viewer window instead of a dedicated window to each camera. The Single window open item is to display opened FITS images in a single FITS Viewer window instead of a dedicated window to each file and the Independent window item is to make FITS Viewer window independent from &kstars;.

The right panel lists processing options. The Auto stretch item is to always apply auto stretch to images in FITS Viewer, Limited resources mode is to enable limited resource mode to turn off any resource-intensive operations, namely: Auto debayer (bayered images will not be debayered; only grayscale images are shown), Auto WCS (World Coordinate System data will not be processed; WCS maps sky coordinates to image coordinates; equatorial grid lines, object identification, and telescope slew within an image are disabled), and 3D cube (RGB images will not be processed; only grayscale images are shown). You can switch off some of these resource-greedy operations separately as well.

## INDI

INDI Window INDI Window

For detailed explanation of the options on the INDI page see the Configure INDI section.

## Ekos

Ekos Window Ekos Window

Ekos is an astrophotography suite, a complete astrophotography solution that can control all INDI devices including numerous telescopes, CCDs, DSLRs, focusers, filters, and a lot more. Ekos supports highly accurate tracking using online and offline astrometry solver, autofocus and autoguiding capabilities, and capture of single or multiple images using the powerful built in sequence manager. For detailed explanation of Ekos, see the Ekos section of this manual.

## Xplanet

Xplanet Window Xplanet Window

Xplanet (should be installed separately) is a solar system planet surface renderer. This page allows you to configure presentation and processing of Xplanet data in &kstars;.

## Advanced

Advanced Window Advanced Window

The Advanced page provides fine-grained control over the more subtle behaviors of &kstars;.

The Correct for atmospheric refraction checkbox controls whether the positions of objects are corrected for the effects of the atmosphere. Because the atmosphere is a spherical shell, light from outer space is bent as it passes through the atmosphere to our telescopes or eyes on the Earth's surface. The effect is largest for objects near the horizon, and actually changes the predicted rise or set times of objects by a few minutes. In fact, when you see a sunset, the Sun's actual position is already well below the horizon; atmospheric refraction makes it seem as if the Sun is still in the sky. Note that atmospheric refraction is never applied if you are using Equatorial coordinates.

The Use animated slewing checkbox controls how the display changes when a new focus position is selected in the map. By default, you will see the sky drift or slew to the new position; if you uncheck this option, then the display will instead snap immediately to the new focus position.

If the Attach label to centered object checkbox is selected, then a name label will automatically be attached to an object when it is being tracked by the program. The label will be removed when the object is no longer being tracked. Note that you can also manually attach a persistent name label to any object with its popup menu.

There are three situations when &kstars; must redraw the sky display very rapidly: when a new focus position is selected (and Use animated slewing is checked), when the sky is dragged with the mouse, and when the time step is large. In these situations, the positions of all objects must be recomputed as rapidly as possible, which can put a large load on the CPU. If the CPU cannot keep up with the demand, then the display will seem sluggish or jerky. To mitigate this, &kstars; will hide certain objects during these rapid-redraw situations, as long as the Hide objects while moving checkbox is selected. The timestep threshold above which objects will be hidden is determined by the Also hide if time step larger than: timestep-spinbox. You can specify the objects that should be hidden in the Configure Hidden Objects section.

## Developer

Developer Window Developer Window

The Developer page provides a few checkboxes that can help debug issues with &kstars;. There are checkboxes for saving images in logging directories that might help debug issues. Of course, saving images can take up disk space and should be used judiciously.

The images that can be saved are

- all focus images,

- all guider images,

- all align images, and

- align images where the plate-solving failed.

The images are all saved in folders parallel to the main logging directory. They are in folders named guide, autofocus, align, and align/failed.

## Customizing the Display

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

- Toggle whether the Info Boxes are drawn in the Settings Info Boxes submenu. 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.

- Toggle whether the Toolbars are drawn in the Settings Toolbars Shown submenu. Like most &kde; toolbars, they can also be dragged around and anchored on any window edge, or even detached from the window completely if they are unlocked.

- Select a different color scheme in the Settings Color Schemes submenu. There are four predefined color schemes, and you can define your own in the Configure - &kstars; window.

- Choose an FOV Symbol using the Settings FOV Symbols submenu. 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 Indicator 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 five available shapes are: Square, Circle, Crosshairs, Bullseye and Semitransparent circle. 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 Symbols submenu.

## Adjusting orientation of the sky map

You can tweak various settings to make the orientation of the sky map match the view through your optical instrument.

First, pick the coordinate system that matches your mount. For an equatorially mounted instrument, switch to the Equatorial Coordinate mode in the View menu or by pressing the Space key. The option to toggle the coordinate system should read Switch to Horizontal View (Horizontal Coordinates) when the current mode is Equatorial Coordinates. For an altazimuth-mounted instrument or naked-eye viewing, switch to Horizontal Coordinates, so that the option in the View menu reads Switch to Star Globe View (Equatorial Coordinates). This sets the base coordinate system used to render the sky map, and also sets the reference for the orientation of the skymap: zenith or north.

If your instrument is using an erecting prism, typically used on Schmidt-Cassegrain and refracting type telescopes, the view through the eyepiece will be mirrored horizontally. You can have the sky map match this by checking the Mirrored View option under the View menu, or using the key combination &Ctrl;&Shift;M.

Next, to rotate the sky map freely, you can hold down the &Shift; key and drag the mouse on the sky map. A temporary overlay will appear showing the direction of north and zenith at the point, and displaying the angle they make with the vertical in a counterclockwise sense. The orientations of zenith and north will update as you rotate the sky map. Letting go of &Shift; or the mouse button will stop the rotation operation. As you pan the sky map or focus it on different objects, the rotation you set is retained as an offset from the reference direction. The reference direction is north when using Equatorial Coordinates and zenith when using Horizontal Coordinates. As a reminder, the reference direction is solid and brighter in the temporary overlay. The temporary overlay also marks the East direction, which will be clockwise from north when mirrored and counter-clockwise when not mirrored. For the two common orientations of erect and inverted, the rotation can be set / reset using the View Skymap Orientation submenu. Select North Down or Zenith Down as is applicable to set an orientation of 180 degrees.

If you are visually observing through an eyepiece of an instrument, you may need to do some more correction. For the common case of a large Dobsonian telescope (or more generally a Newtonian design mounted on an altazimuth mount), an additional systematic correction is of help. This correction applies because we stand erect while using the telescope irrespective of the angle the telescope tube is making with the ground. So as we move the telescope in altitude, an additional correction depending on the altitude of the object needs to be applied to make the sky map match the view through the eyepiece where the observer is standing erect. This correction is enabled by choosing the appropriate "Erect observer correction" option in the View Skymap Orientation submenu. The correction depends on which side the telescope's focuser is placed by the manufacturer. If when observing just above the horizon through the eyepiece, the sky is on the observer's right side (and the mirror to the left), pick the Erect observer correction, right-handed option. Similarly, if the sky is to the left of the observer, choose the Erect observer correct, left-handed option. This correction only makes sense in Horizontal Coordinate mode and is disabled when using equatorial coordinates.

We now provide some examples of how to use these settings for various instruments:

- Naked-eye observing: Choose Horizontal Coordinates and a Zenith Up orientation under View Skymap Orientation.

- Camera on an equatorially mounted telescope: Choose Equatorial Coordinates and adjust the orientation of the sky map so that it matches your camera. As your mount points to different regions of the sky, the orientation should be rendered correctly.

- Using binoculars: Same settings as Naked-eye observing

- Eyepiece of an altazimuth Schmidt-Cassegrain telescope with an erecting prism: Under the View menu, choose Mirrored View, and under the Skymap Orientation sub-menu, choose Zenith Up. Finally, tweak the rotation manually to match the eyepiece view according to the angle you are using for your erecting prism.

- Using a RACI finder scope on an altazimuth mounted telescope, looking straight down into it: Same settings as Naked-eye observing, except you may need to tweak the orientation manually once if you have it mounted at an angle

- Using a RACI finder scope on an altazimuth mounted telescope, looking through it from the side: In addition to the aforementioned, enable Erect observer correction for the appropriate side.

- Using a straight-through (inverted view) finder scope on an altazimuth mounted telescope: Choose Horizontal Coordinates and a sky-map orientation of Zenith Down in View Skymap Orientation submenu

- Eyepiece of a Dobsonian telescope: Choose Horizontal Coordinates, and in the View Skymap Orientation submenu, select Zenith Down and enable the erect observer correction, picking the left/right handed option as is appropriate for your telescope. Then adjust the orientation manually once to match your telescope eyepiece view, and it should henceforth track it correctly.

It is typical in visual astronomy to use at least three different instruments: the unaided eye, a finder scope, and the main telescope. The orientations of these three will have different settings and will need frequent modification of all the aforementioned options. To make it easy to adjust these settings together, KStars provides the Views feature. This feature is accessible through the View Views menu and the options contained therein. The Arbitrary view is not a real view, but the option that gets selected when the sky-map orientation is modified manually through the previously described options. The rest of the views are bona fide views. New views may be added, or the existing views may be edited, removed, or re-ordered using the View Views Edit Views... option. Choosing this brings up a window to manage the views:

Dialog to manage sky map views Manage Sky Map Views

To remove a view, simply select the view from the list and delete it using the Remove button. To re-order the views, use the mouse to drag the view you wish to move and drop it at its destination in-between two other entries. To edit a view, select the view from the list and click Edit.... To create a new view, click the New... button. The Edit... and New... options bring up a view editor interface:

Dialog to create a new view or edit an existing one Edit / Create View

The Name field carries a unique name for the View. The Mount Type determines whether the reference direction used for orientation will be north or zenith. Typically, one would set this to the type of mount used for the telescope. However, when using refractors and Schmidt-Cassegrain Telescopes (SCTs) with a rotatable diagonal, the observer will have a tendency to re-orient the eyepiece for comfort so that the eyepiece remains at a fixed angle with respect to the zenith. For this reason, it makes sense to choose Altazimuth mounting even when the telescope is actually on an equatorial mount. Choose Equatorial mounting when the focuser will not be re-oriented, such as when using a camera on an equatorially mounted telescope. For Newtonian telescopes that invert (i.e. rotate by 180 degrees but do not change the handedness) of the view, pick the Inverted option. This is also the correct option for straight-through refractors and finder scopes. When using a erecting prism diagonal, the prism erects the inverted image by flipping it up-down. This results overall in a left-right mirrored image. Thus for telescopes that use an erecting prism, pick Mirrored. A special kind of prism called an Amici roof prism not only erects the image vertically, but it also prevents left-right mirroring of the image. Finder scopes incorporating such a diagonal are normally called "Right-Angle Correct Image" or RACI finder scopes. Such diagonals may also be used on refractors and SCTs. When using such a prism that produces a correct image, choose the Correct option. The Mirrored on the vertical axis option is not encountered in typical astronomical instruments, but is provided for completeness. Two more factors need to be considered: one is the angle of the eyepiece with respect to the reference direction (north / zenith), and the other is the orientation of the observer's head (and notion of the vertical) which we explained when describing the erect observer correction feature. These two aspects are configured using the single slider titled Eyepiece Angle. Two illustrations below the slider show the interpretation of this setting; on the left, as seen from the front as is more convenient for Newtonian telescopes, and on the right as is seen from the back, more convenient for refractors and Cassegrains. The observer naturally stands on the side that makes it more convenient to look through the eyepiece, so the erect observer correction is automatically adjusted accordingly. For eyepiece angles that are less than -1 degree on the slider, the Erect observer correction, right-handed option is applied. Similarly, for eyepiece angles that are greater than +1 degree, the Erect observer correction, left-handed is applied. At 0 degrees, no erect observer correction is applied. This correction is indicated by a silhouette of a person standing on the appropriate side of the telescope. In our convention, most mass-manufactured Dobsonians seem to have a correction around +45 degrees. Incidentally, this correction is also useful for finder scopes with diagonals. One may want to explicitly disable the erect observer correction even when the eyepiece angle is not zero. This is useful in case the view comes from a CCD camera that does not change angle with respect to the telescope body (unlike an observer's head), or if the display showing KStars' sky map is mounted on the telescope body itself. In this case the Display mounted on the telescope option can be checked. For the opposite effect, i.e. where the eyepiece angle is zero, but the observer is leaning to look through the eyepiece from one of the two sides, set the eyepiece angle to plus or minus 2 degrees to enable the erect observer correction; the minor difference will not be noticeable. Finally, one may want triggering of the view to also set the field-of-view of the sky map to some value, for example to set the FOV of a finder scope. In this case, the Also set the field of view check-box may be checked, and an approximate field-of-view to adjust may be specified. If this is not enabled, the zoom level of the sky map is not altered when this view is applied.

&hips;