path: root/doc/kstars/config.docbook

<chapter id="config">
<title>Configuring &kstars;</title>

<sect1 id="setgeo">
<title>Setting the Geographic Location</title>

<para>
Here is a screenshot of the <guilabel>Set Geographic Location</guilabel>
window:
<screenshot>
<screeninfo>Changing the Geographic Location</screeninfo>
<mediaobject>
  <imageobject>
    <imagedata fileref="geolocator.png" format="PNG"/>
  </imageobject>
  <textobject>
    <phrase>Set Location Window</phrase>
  </textobject>
</mediaobject>
</screenshot>
</para>

<para>
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.
</para>

<para>
<indexterm><primary>Geographic Location Tool</primary>
<secondary>Filtering</secondary></indexterm>
It is not 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 <quote>Ba</quote> appears in the
<guilabel>City Filter</guilabel> box, while <quote>M</quote> has been
entered in the <guilabel>Province Filter</guilabel> box, and
<quote>USA</quote> is in the <guilabel>Country Filter</guilabel>
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.
</para><para>
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.
</para><para>
<indexterm><primary>Geographic Location Tool</primary>
<secondary>Custom locations</secondary></indexterm>
The <link linkend="ai-geocoords">longitude, latitude</link> and
<link linkend="ai-timezones">time zone</link> 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 <guibutton>Add to List</guibutton> button
to record your custom version of the location.  You can also define a
completely new location by pressing the
<guibutton>Clear Fields</guibutton> button, and entering the data for
the new location.  Note that all fields except the optional
<guilabel>State/Province</guilabel> 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
<filename>~/.trinity/share/apps/kstars/mycities.dat</filename>.
</para><para>
If you add custom locations (or modify existing ones), please send us
your <filename>mycities.dat</filename> file so that we can add your
locations to the master list.
</para>
</sect1>

<sect1 id="settime">
<title>Setting the Time</title>
<para>
<indexterm><primary>Date and Time</primary>
<secondary>The simulation clock</secondary></indexterm>
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 <guimenuitem>Stop
Clock</guimenuitem> from the <guimenu>Time</guimenu> menu, or simply
click on the <guiicon>Pause</guiicon> 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.
</para>
<para>
<indexterm><primary>Date and Time</primary>
<secondary>Setting</secondary></indexterm>
You can set the  time and date by selecting <guimenuitem>Set
Time...</guimenuitem> from the <guimenu>Time</guimenu> menu, or by
pressing the <guiicon>time</guiicon> icon in the toolbar.  The
<guilabel>Set Time</guilabel> window uses a standard &kde; Date Picker
widget, coupled with three spinboxes for setting the hours, minutes and
seconds.  If you want to re-synchronize the simulation clock back to the
current CPU time, just select <guimenuitem>Set Time to Now</guimenuitem>
from the <guimenu>Time</guimenu> menu.</para>

<note><para>
<indexterm><primary>Date and Time</primary>
<secondary>Extended range of dates</secondary></indexterm>
&kstars; can accept very remote dates beyond the usual limits imposed by
QDate.  Currently, you can set the date between the years -50000 and +50000.
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.
</para></note>
</sect1>

<sect1 id="viewops">
<title>The Configure &kstars; Window</title>
<para>
<indexterm><primary>Configure &kstars; window</primary></indexterm>
The <guilabel>Configure &kstars;</guilabel> window allows you to modify
a wide range of display options.  You can access the window with the
<guiicon>configure</guiicon> toolbar icon, or by selecting
<guimenuitem>Configure &kstars;...</guimenuitem> from the
<guimenu>Settings</guimenu> menu.
The window is depicted below:

<screenshot>
<screeninfo>Configure &kstars; Window</screeninfo>
<mediaobject>
  <imageobject>
    <imagedata fileref="viewops.png" format="PNG"/>
  </imageobject>
  <textobject>
    <phrase>Configure &kstars; Window</phrase>
  </textobject>
</mediaobject>
</screenshot>
</para>

<para>
The <guilabel>Configure &kstars;</guilabel> window is divided into five
tabs:
<guilabel>Catalogs</guilabel>, <guilabel>Guides</guilabel>,
<guilabel>Solar System</guilabel>, <guilabel>Colors</guilabel>, and
<guilabel>Advanced</guilabel>.
</para>
<para>
<indexterm><primary>Configure &kstars; window</primary>
<secondary>Catalogs Tab</secondary></indexterm>
In the <guilabel>Catalogs</guilabel> tab, you determine which object
catalogs are displayed in the map.  The <guilabel>Stars</guilabel> section
also allows you to set the
<quote>faint <link linkend="ai-magnitude">magnitude</link> limit</quote>
for stars, and the <link linkend="ai-magnitude">magnitude</link> limit for
displaying the names and/or magnitudes of stars.  Below the stars section,
the <guilabel>Deep-Sky Objects</guilabel> section controls the display of
several non-stellar object catalogs.  By default, the list includes the
Messier, NGC and IC catalogs.  You can add your own custom object catalogs
by pressing the <guibutton>Add Custom Catalog</guibutton> button.  For
detailed instructions on preparing a catalog data file, see the
<filename>README.customize</filename> file that ships with &kstars;.
</para>
<para>
<indexterm><primary>Configure &kstars; window</primary>
<secondary>Solar System Tab</secondary></indexterm>
In the <guilabel>Solar System</guilabel> tab, 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 <quote>orbit
trail</quote> whenever a solar system body is tracked, and another to
toggle whether the color of the orbit trail fades into the background
sky color.
</para>
<para>
<indexterm><primary>Configure &kstars; window</primary>
<secondary>Guides Tab</secondary></indexterm>
The <guilabel>Guides</guilabel> tab lets you toggle whether non-objects
are displayed (&ie;, constellation lines, constellation names, the
Milky Way contour, the <link linkend="ai-cequator">celestial
equator</link>, <link linkend="ai-ecliptic">the ecliptic</link>, <link
linkend="ai-horizon">the horizon line</link>, and the opaque ground).
You can also choose whether you would like to see Latin constellation
names, <acronym>IAU</acronym>-standard three-letter abbreviations, or
constellation names using your local language.
</para>
<para>
<indexterm><primary>Configure &kstars; window</primary>
<secondary>Colors Tab</secondary></indexterm>
<indexterm><primary>Color Schemes</primary>
<secondary>Customizing</secondary></indexterm>
The <guilabel>Colors</guilabel> tab allows you to set the color scheme,
and to define custom color schemes.  The tab is split into two panels:
</para>
<para>
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 <guilabel>Star Color
Mode</guilabel> selection box.  By default, &kstars; draws stars with
a <link linkend="ai-colorandtemp">realistic color</link> 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 <guilabel>Star Color Intensity</guilabel> spinbox.
</para>
<para>
The right panel lists the defined color schemes.  There are four
predefined schemes: the <guilabel>Default</guilabel> scheme,
<guilabel>Star Chart</guilabel>, which uses black stars on a white
background, <guilabel>Night Vision</guilabel>, which uses only shades
of red in order to protect dark-adapted vision, and <guilabel>Moonless
Night</guilabel>, a more realistic, dark theme.  Additionally,
you can save the current color settings as a custom scheme by clicking
the <guibutton>Save Current Colors</guibutton> 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 <guibutton>Remove Color
Scheme</guibutton> button.
</para><para>
<indexterm><primary>Configure &kstars; window</primary>
<secondary>Advanced Tab</secondary></indexterm>
The <guilabel>Advanced</guilabel> Tab provides fine-grained control
over the more subtle behaviors of &kstars;.
</para><para>
<indexterm><primary>Atmospheric Refraction</primary></indexterm>
The <guilabel>Correct for atmospheric refraction</guilabel> 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 <quote>bent</quote> 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 <quote>see</quote> 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
<guilabel>Equatorial coordinates</guilabel>.
</para><para>
<indexterm><primary>Animated Slewing</primary></indexterm>
The <guilabel>Use animating slewing</guilabel> 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 <quote>slew</quote> to the new
position; if you uncheck this option, then the display will instead
<quote>snap</quote> immediately to the new focus position.
</para><para>
<indexterm><primary>Objects in the Sky</primary>
<secondary>Labeling</secondary>
<tertiary>Automatic</tertiary>
</indexterm>
If the <guilabel>Attach label to centered object</guilabel> 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 <link
linkend="popup-menu">popup menu</link>.
</para><para>
<indexterm><primary>Objects in the Sky</primary>
<secondary>Hiding</secondary></indexterm>
There are three situations when &kstars; must redraw the sky display very
rapidly: when a new focus position is selected (and <guilabel>Use
animated slewing</guilabel> 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 <abbrev>CPU</abbrev>.  If the <abbrev>CPU</abbrev>
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 <guilabel>Hide objects while moving</guilabel>
checkbox is selected.  The timestep threshold above which objects will be
hidden is determined by the <guilabel>Also hide if timescale greater
than:</guilabel> timestep-spinbox.  You can specify the objects that should
be hidden in the <guilabel>Configure Hidden Objects</guilabel> group box.
</para>
</sect1>

<sect1 id="customize">
<title>Customizing the Display</title>

<para>
There are several ways to modify the display to your liking.</para>
<itemizedlist>
<listitem><para>
<indexterm><primary>Color Schemes</primary><secondary>Selecting</secondary></indexterm>
Select a different color scheme in the
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Color Schemes</guimenuitem></menuchoice>
menu.  There are four predefined color schemes, and you can define your own in the
<link linkend="config"><guilabel>Configure &kstars;</guilabel></link> window.
</para></listitem>
<listitem><para>
<indexterm><primary>Toolbars</primary>
<secondary>Customizing</secondary></indexterm>
Toggle whether the Toolbars are drawn in the
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Toolbars</guimenuitem></menuchoice>
menu.  Like most KDE toolbars, they can also be dragged around and
anchored on any window edge, or even detached from the window completely.
</para></listitem>
<listitem><para>
<indexterm><primary>Info Boxes</primary><secondary>Customizing</secondary></indexterm>
<indexterm><primary>Info Boxes</primary><secondary>Shading</secondary></indexterm>
Toggle whether the Info Boxes are drawn in the
<menuchoice><guimenu>Settings</guimenu><guimenuitem>Info Boxes</guimenuitem></menuchoice>
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 <quote>shade</quote> it.  Also, you can reposition a box by
dragging it with the mouse.  When a box hits a window edge, it will
<quote>stick</quote> to the edge when the window is resized.
</para></listitem>
<listitem>
<para>
<indexterm><primary>Field-of-View Symbols</primary><secondary>Description</secondary></indexterm>
Choose an <quote>FOV Symbol</quote> using the
<menuchoice><guimenu>Settings</guimenu><guimenuitem>FOV Symbols</guimenuitem></menuchoice>
menu.  <firstterm>FOV</firstterm> is an acronym for <quote>field-of-view</quote>.
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 <quote>7x35 Binoculars</quote> 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.
</para>
<para>
<indexterm><primary>Field-of-View Symbols</primary><secondary>Customizing</secondary></indexterm>
You can define your own FOV symbols (or modify the existing symbols) using the
<guimenuitem>Edit FOV Symbols...</guimenuitem> menu item, which launches the FOV Editor:
</para>
<screenshot>
<screeninfo>Field-of-View Symbols Editor</screeninfo>
<mediaobject>
  <imageobject>
    <imagedata fileref="fovdialog.png" format="PNG"/>
  </imageobject>
  <textobject>
    <phrase>FOV Symbol Editor</phrase>
  </textobject>
</mediaobject>
</screenshot>

<para>
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 <guibutton>New...</guibutton> or
<guibutton>Edit...</guibutton> button is pressed, the <guilabel>New FOV Symbol</guilabel>
window is opened:
</para>

<screenshot>
<screeninfo>New Field-of-View Symbol</screeninfo>
<mediaobject>
  <imageobject>
    <imagedata fileref="newfov.png" format="PNG"/>
  </imageobject>
  <textobject>
    <phrase>New FOV Symbol</phrase>
  </textobject>
</mediaobject>
</screenshot>

<para>
<indexterm><primary>Field-of-View Symbols</primary><secondary>Defining New</secondary></indexterm>
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
<guilabel>Field of View</guilabel> 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 <guibutton>Ok</guibutton>,
and the symbol will appear in the list of defined symbols.  It will also be available
from the <guimenu>Settings</guimenu> | <guisubmenu>FOV</guisubmenu> menu.
</para>
</listitem>
</itemizedlist>

</sect1>

</chapter>