Warning, /education/kstars/doc/config.docbook is written in an unsupported language. File is not indexed.

0001 <chapter id="config">
0002 <title>Configuring &kstars;</title>
0003 
0004 <sect1 id="setgeo">
0005 <title>Setting the Geographic Location</title>
0006 
0007 <para>
0008 Here is a screenshot of the <guilabel>Set Geographic Location</guilabel>
0009 window:
0010 <screenshot>
0011 <screeninfo>Changing the Geographic Location</screeninfo>
0012 <mediaobject>
0013   <imageobject>
0014     <imagedata fileref="geolocator.png" format="PNG"/>
0015   </imageobject>
0016   <textobject>
0017     <phrase>Set Location Window</phrase>
0018   </textobject>
0019 </mediaobject>
0020 </screenshot>
0021 </para>
0022 
0023 <para>
0024 There is a list of over 3400 predefined cities available to choose from.
0025 You set your location by highlighting a city from this list.  Each
0026 city is represented in the world map as a small dot, and when a city
0027 is highlighted in the list, a red crosshairs appears on its location
0028 in the map.
0029 </para>
0030 
0031 <para>
0032 <indexterm><primary>Geographic Location Tool</primary>
0033 <secondary>Filtering</secondary></indexterm>
0034 It is not practical to scroll through the full list of 3400 locations,
0035 looking for a specific city. To make searches easier, the list can be
0036 filtered by entering text in the boxes below the map. For example, in
0037 the screenshot, the text <userinput>A</userinput> appears in the
0038 <guilabel>City filter:</guilabel> box, while <userinput>Te</userinput> has been
0039 entered in the <guilabel>Province filter:</guilabel> box, and
0040 <userinput>USA</userinput> is in the <guilabel>Country filter:</guilabel>
0041 box. Note that all of the cities displayed in the list have city,
0042 province, and country names that begin with the entered filter
0043 strings, and that the message below the filter boxes indicates that 6
0044 cities are matched by the filters.  Also notice that the dots
0045 representing these six cities in the map have been colored white,
0046 while the unmatched cities remain gray.
0047 </para><para>
0048 The list can also be filtered by location in the map.  Clicking anywhere
0049 in the world map will show only those cities within two degrees of the
0050 clicked location.  At this time, you can search by name, or by location,
0051 but not both at once.  In other words, when you click on the map, the
0052 name filters are ignored, and vice versa.
0053 </para><para>
0054 <indexterm><primary>Geographic Location Tool</primary>
0055 <secondary>Custom locations</secondary></indexterm>
0056 The <link linkend="ai-geocoords">longitude, latitude</link> and
0057 <link linkend="ai-timezones">time zone</link> information for the
0058 currently-selected location are displayed in the boxes at the bottom of
0059 the window.  If you feel that any of these values are inaccurate, you
0060 can modify them and press the <guibutton>+</guibutton> (Add City) button
0061 to record your custom version of the location.  You can also define a
0062 completely new location by pressing the
0063 <guibutton>Clear Fields</guibutton> button, and entering the data for
0064 the new location.  Note that all fields except the optional
0065 <guilabel>Province:</guilabel>/<guilabel>Country:</guilabel> must be filled before the new
0066 location can be added to the list.  &kstars; will automatically load
0067 your custom locations for all future sessions.  Please note, at this
0068 point, the only way to remove a custom location is to remove the
0069 appropriate line from the file <filename>kstars/mycities.dat</filename>
0070 in your folder <userinput><command>qtpaths</command> <option>--paths GenericDataLocation</option></userinput>&nbsp;.
0071 </para><para>
0072 If you add custom locations (or modify existing ones), please send us
0073 your <filename>mycities.dat</filename> file so that we can add your
0074 locations to the master list.
0075 </para>
0076 </sect1>
0077 
0078 <sect1 id="settime">
0079 <title>Setting the Time</title>
0080 <para>
0081 <indexterm><primary>Date and Time</primary>
0082 <secondary>The simulation clock</secondary></indexterm>
0083 When &kstars; starts up, the time is set to your computer's system
0084 clock, and the &kstars; clock is running to keep up with the real time.
0085 If you want to stop the clock, select the <menuchoice><guimenu>Time</guimenu>
0086 <guimenuitem>Stop Clock</guimenuitem></menuchoice> menu item, or simply
0087 click on the <guiicon>Stop Clock</guiicon> icon in the toolbar.  You can
0088 make the clock run slower or faster than normal, or even make it run
0089 backward, using the time-step spinbox in the toolbar.  This spinbox
0090 has two sets of up/down buttons.  The first one will step through all
0091 83 available time steps, one by one.  The second one will skip to the
0092 next higher (or lower) unit of time, which allows you to make large
0093 timestep changes more quickly.
0094 </para>
0095 <para>
0096 <indexterm><primary>Date and Time</primary>
0097 <secondary>Setting</secondary></indexterm>
0098 You can set the  time and date by selecting the <menuchoice><guimenu>Time</guimenu>
0099 <guimenuitem>Set Time...</guimenuitem></menuchoice> menu item, or by
0100 pressing the <guiicon>Time</guiicon> icon in the toolbar.  The
0101 <guilabel>Set Time</guilabel> window uses a standard &kde; Date Picker
0102 widget, coupled with a spinbox for setting the hours and minutes.
0103 If you want to re-synchronize the simulation clock back to the
0104 current CPU time, just select the <menuchoice><guimenu>Time</guimenu> <guimenuitem>Set
0105 Time to Now</guimenuitem></menuchoice> menu item.</para>
0106 
0107 <note><para>
0108 <indexterm><primary>Date and Time</primary>
0109 <secondary>Extended range of dates</secondary></indexterm>
0110 &kstars; can accept very remote dates beyond the usual limits imposed by
0111 QDate.  Currently, you can set the date between the years -100000 and +100000.
0112 We may extend this range even further in future releases.  However, please
0113 be aware that the accuracy of the simulation becomes more and more degraded
0114 as more remote dates are examined.  This is especially true for the positions
0115 of solar system bodies.
0116 </para></note>
0117 </sect1>
0118 
0119 <sect1 id="viewops">
0120 <title>The Configure &kstars; Window</title>
0121 <para>
0122 <indexterm><primary>Configure &kstars; window</primary></indexterm>
0123 The <guilabel>Configure - &kstars;</guilabel> window allows you to modify
0124 a wide range of display options.  You can access the window with the
0125 <guiicon>Configure</guiicon> toolbar icon, or by selecting the
0126 <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Configure 
0127 &kstars;...</guimenuitem></menuchoice> menu item.
0128 The window is depicted below:
0129 
0130 <screenshot>
0131 <screeninfo>Configure - &kstars; Window</screeninfo>
0132 <mediaobject>
0133   <imageobject>
0134     <imagedata fileref="viewops.png" format="PNG"/>
0135   </imageobject>
0136   <textobject>
0137     <phrase>Configure - &kstars; Window</phrase>
0138   </textobject>
0139 </mediaobject>
0140 </screenshot>
0141 </para>
0142 
0143 <para>
0144 The <guilabel>Configure - &kstars;</guilabel> window is divided into twelve pages:
0145 <guilabel>Catalogs</guilabel>, <guilabel>Solar System</guilabel>, <guilabel>Satellites</guilabel>,
0146 <guilabel>Supernovae</guilabel>, <guilabel>Guides</guilabel>, <guilabel>Terrain</guilabel>, <guilabel>Colors</guilabel>, <guilabel>FITS</guilabel>,
0147 <guilabel>INDI</guilabel>, <guilabel>Ekos</guilabel>, <guilabel>Xplanet</guilabel> and <guilabel>Advanced</guilabel>.
0148 </para>
0149 
0150 <!-- Catalogs page: -->
0151 <para>
0152 <indexterm><primary>Configure &kstars; window</primary>
0153 <secondary>Catalogs page</secondary></indexterm> In
0154 the <guilabel>Catalogs</guilabel> page, you determine several
0155 properties concerning the display of the star and deep sky object catalogs.
0156 </para>
0157 
0158 <!-- Solar System page: -->
0159 <para>
0160 <indexterm><primary>Configure &kstars; window</primary>
0161 <secondary>Solar System page</secondary></indexterm>
0162 In the <guilabel>Solar System</guilabel> page, you can specify whether
0163 the Sun, Moon, planets, comets and asteroids are displayed.
0164 </para>
0165 
0166 <!-- Satellites page: -->
0167 <para>
0168 <indexterm><primary>Configure &kstars; window</primary>
0169 <secondary>Satellites page</secondary></indexterm>
0170 The <guilabel>Satellites</guilabel> page allows you to set the satellites view options.
0171 </para>
0172 
0173 <!-- Supernovae page: -->
0174 <para>
0175 <indexterm><primary>Configure &kstars; window</primary>
0176 <secondary>Supernovae page</secondary></indexterm>
0177 The <guilabel>Supernovae</guilabel> page allows you to manage how supernovae are displayed by &kstars;.
0178 </para>
0179 
0180 <!-- Guides page: -->
0181 <para>
0182 <indexterm><primary>Configure &kstars; window</primary>
0183 <secondary>Guides page</secondary></indexterm>
0184 The <guilabel>Guides</guilabel> page lets you toggle whether non-objects
0185 are displayed (&ie;, constellation lines, constellation names, the
0186 Milky Way contour).
0187 </para>
0188 
0189 <variablelist>
0190   <varlistentry>
0191     <term></term><listitem><para><indexterm><primary>Sky culture</primary></indexterm>
0192     It is possible to choose a <guilabel>Sky culture:</guilabel> for the constellation lines and names on this page. The current version of &kstars; includes data for more than a dozen sky cultures.
0193     </para></listitem>
0194   </varlistentry>
0195 </variablelist>
0196 
0197 <!-- Terrain page: -->
0198 <para>
0199 <indexterm><primary>Configure &kstars; window</primary>
0200 <secondary>Terrain page</secondary></indexterm>
0201 <indexterm><primary>Terrain image</primary>
0202 <secondary>Customizing</secondary></indexterm>
0203 The <guilabel>Terrain</guilabel> page allows you to set the terrain or landscape image
0204 and configure its speedup options.
0205 </para>
0206 
0207 <!-- Colors page: -->
0208 <para>
0209 <indexterm><primary>Configure &kstars; window</primary>
0210 <secondary>Colors page</secondary></indexterm>
0211 <indexterm><primary>Color Schemes</primary>
0212 <secondary>Customizing</secondary></indexterm>
0213 The <guilabel>Colors</guilabel> page allows you to set the color scheme,
0214 and to define new custom color schemes.
0215 </para>
0216 
0217 <!-- FITS page: -->
0218 <para>For detailed explanation of the options on the <guilabel>FITS</guilabel>
0219 page see the <link linkend="fits-configure">Configure FITS</link> section.
0220 </para>
0221 
0222 <!-- INDI page: -->
0223 <para>For detailed explanation of the options on the <guilabel>INDI</guilabel>
0224 page see the <link linkend="indi-configure">Configure INDI</link> section.
0225 </para>
0226 
0227 <!-- Ekos page: -->
0228 <para>For detailed explanation of <guilabel>Ekos</guilabel> astrophotography suite,
0229 see the <link linkend="tool-ekos">Ekos section of this manual</link>.
0230 </para>
0231 
0232 <!-- Xplanet page: -->
0233 <para>
0234 <indexterm><primary>Configure &kstars; window</primary>
0235 <secondary>Xplanet page</secondary></indexterm>
0236 The <guilabel>Xplanet</guilabel> page provides fine-grained control
0237 over <ulink url="http://xplanet.sourceforge.net/">Solar system planet surface renderer Xplanet</ulink> (should be installed separately).
0238 </para>
0239 
0240 <!-- Advanced page: -->
0241 <para>
0242 <indexterm><primary>Configure &kstars; window</primary>
0243 <secondary>Advanced page</secondary></indexterm>
0244 The <guilabel>Advanced</guilabel> page provides fine-grained control
0245 over the more subtle behaviors of &kstars;.
0246 </para>
0247 </sect1>
0248 
0249 <sect1 id="catalogs">
0250 <title>Catalogs</title>
0251 <para>
0252   <indexterm><primary>Catalogs</primary></indexterm>
0253 <screenshot>
0254 <screeninfo>Catalogs Window</screeninfo>
0255 <mediaobject>
0256   <imageobject>
0257     <imagedata fileref="viewops.png" format="PNG"/>
0258   </imageobject>
0259   <textobject>
0260     <phrase>Catalogs Window</phrase>
0261   </textobject>
0262 </mediaobject>
0263 </screenshot>
0264 </para>
0265 
0266 <para>
0267 <indexterm><primary>Catalogs page</primary>
0268 <secondary>Short overview</secondary></indexterm> In the
0269 <guilabel>Catalogs</guilabel> page, you can configure which object
0270 catalogs are displayed by &kstars;, as well as how much information
0271 you would like to be included on the Sky Map. By default, &kstars;
0272 includes ~300,000 named and unnamed stars up to magnitude 8. For Deep
0273 Sky Objects, the included catalog is the New General Catalog
0274 (<quote>NGC</quote>) including the Index Catalog (<quote>IC</quote>)
0275 and the Messier Catalog.
0276 </para>
0277 
0278 <para>
0279 The New General Catalog of Nebulae and Clusters of Stars
0280 (abbreviated as NGC) is a catalog of ca 7,840 deep-sky objects.
0281 </para>
0282 
0283 <para>
0284 The Index Catalog of Nebulae and Clusters of Stars (abbreviated as
0285 IC) serves as a supplement to the NGC, and contains an additional
0286 5,386 objects, collectively known as the IC objects.
0287 </para>
0288 
0289 <para>
0290 You can install new catalogs using &kstars; <quote>Add-On Installer</quote>. You can open it
0291 via the <menuchoice><guimenu>Data</guimenu> <guimenuitem>Download New Data...</guimenuitem></menuchoice> menu item.
0292 You can choose from a list of catalogs, including (but not limited to):
0293 <itemizedlist>
0294 
0295 <listitem><para>
0296 Steinicke NGC/IC Catalog: is a more complete NGC/IC catalog.
0297 </para></listitem>
0298 
0299 <listitem><para>
0300 Abell Planetary Nebulae Catalog: is a catalog of 86 planetary nebulae. The
0301 maximum magnitude is represented by Abell 47's value of 19.5.
0302 </para></listitem>
0303 
0304 <listitem><para>
0305 Sharpless HII region Catalog: is the Sharpless (Sh2) catalog of HII regions (diffuse nebulae).
0306 </para></listitem>
0307 
0308 <listitem><para>
0309 Hickson Compact Groups: is a catalog consisting of 99 compact groups of galaxies.
0310 </para></listitem>
0311 
0312 <listitem><para>
0313 Tycho-2 Star Catalog: is a catalog of more than 2.5 million of the brightest stars. It contains
0314 stars with a magnitude value from 8.0 to 12.5.
0315 </para></listitem>
0316 
0317 <listitem><para>
0318 USNO NOMAD Catalog: is a catalog of about 100 million stars with magnitude from 12.5 to 16.5.
0319 Note that is requires Tycho-2 to be installed.
0320 </para></listitem>
0321 
0322 </itemizedlist>
0323 </para>
0324 
0325 <para>
0326 The following is a summary of catalogs in &kstars;:
0327 
0328 <table frame="top"><title>Stars Catalogs</title>
0329 <tgroup cols="4" colsep="1" rowsep="1">
0330 <thead>
0331 <row>
0332 <entry>Name</entry>
0333 <entry>Abbreviation</entry>
0334 <entry>Number of objects</entry>
0335 <entry>Magnitude</entry>
0336 <entry>Add-On</entry>
0337 <entry>Default</entry>
0338 </row>
0339 </thead>
0340 <tbody>
0341 <row>
0342 <entry>Default Catalog</entry>
0343 <entry>Default</entry>
0344 <entry>~300,000</entry>
0345 <entry>Up to 8 magnitude</entry>
0346 <entry>No</entry>
0347 <entry>Yes</entry>
0348 </row>
0349 <row>
0350 <entry>Tycho-2</entry>
0351 <entry>Tycho2</entry>
0352 <entry>more than 2.5 million</entry>
0353 <entry>8.0-12.5 </entry>
0354 <entry>Yes</entry>
0355 <entry>No</entry>
0356 </row>
0357 <row>
0358 <entry>Naval Observatory Merged Astronomic Dataset</entry>
0359 <entry>USNO NOMAD</entry>
0360 <entry>100 million</entry>
0361 <entry>12.5-16.5</entry>
0362 <entry>Yes</entry>
0363 <entry>No</entry>
0364 </row>
0365 </tbody>
0366 </tgroup>
0367 </table>
0368 
0369 <table frame="top"><title>Deep-sky objects Catalogs</title>
0370 <tgroup cols="4" colsep="1" rowsep="1">
0371 <thead>
0372 <row>
0373 <entry>Name</entry>
0374 <entry>Abbreviation</entry>
0375 <entry>Number of objects</entry>
0376 <entry>Magnitude</entry>
0377 <entry>Add-On</entry>
0378 <entry>Default</entry>
0379 </row>
0380 </thead>
0381 <tbody>
0382 <row>
0383 <entry>New General Catalog of Nebulae and Clusters of Stars (OpenNGC)</entry>
0384 <entry>NGC</entry>
0385 <entry>7,840</entry>
0386 <entry>-</entry>
0387 <entry>No</entry>
0388 <entry>Yes</entry>
0389 </row>
0390 <row>
0391 
0392 <entry>Steinicke NGC/IC</entry>
0393 <entry>-</entry>
0394 <entry>-</entry>
0395 <entry>-</entry>
0396 <entry>Yes</entry>
0397 <entry>No</entry>
0398 </row>
0399 
0400 <row>
0401 <entry>Abell Planetary Nebulae Catalog</entry>
0402 <entry>-</entry>
0403 <entry>86</entry>
0404 <entry>Up to 19.5 magnitude</entry>
0405 <entry>Yes</entry>
0406 <entry>No</entry>
0407 </row>
0408 
0409 <row>
0410 <entry>Sharpless HII region Catalog</entry>
0411 <entry>Sh2</entry>
0412 <entry>-</entry>
0413 <entry>-</entry>
0414 <entry>Yes</entry>
0415 <entry>No</entry>
0416 </row>
0417 
0418 <row>
0419 <entry>Hickson Compact Groups</entry>
0420 <entry>-</entry>
0421 <entry>99</entry>
0422 <entry>-</entry>
0423 <entry>Yes</entry>
0424 <entry>No</entry>
0425 </row>
0426 
0427 </tbody>
0428 </tgroup>
0429 </table>
0430 <note>
0431   <para>A potentially more up-to-date listing can be found in
0432     the <ulink url="https://protagon.space/catalogs/pages/catalogs.html">catalog
0433       repository documentation</ulink>.
0434   </para>
0435 </note>
0436 </para>
0437 
0438 <para>
0439 <indexterm><primary>Catalogs</primary>
0440 <secondary>Star catalogs</secondary></indexterm>
0441 The <guilabel>Stars</guilabel> section allows you to manage how stars are
0442 displayed in &kstars;. You can choose to see the stars or not by checking the
0443 <guilabel>Star catalogs</guilabel> checkbox. If you check it, then multiple
0444 options will be enabled. Thus, you can set how many stars are drawn on the map
0445 using the <guilabel>Star density:</guilabel> slider. You can also customize
0446 &kstars; to toggle star name and <link linkend="ai-magnitude">magnitudes</link>.
0447 Star names are drawn next to bright stars. To display labels of fainter stars,
0448 increase the <guilabel>Label density:</guilabel> slider.
0449 </para>
0450 
0451 <para>
0452 <indexterm><primary>Catalogs</primary>
0453 <secondary>Deep-Sky Catalogs</secondary></indexterm>
0454 Below the stars section, the <guilabel>Deep-Sky Objects</guilabel> section controls
0455 the display of several non-stellar object catalogs. You can toggle the display of
0456 Deep Sky Objects and control the display of their names and magnitudes. By default,
0457 the list of deep-sky objects includes the Messier, NGC and IC catalogs.
0458 Addons catalogs are available via the
0459 <menuchoice><guimenu>Data</guimenu> <guimenuitem>Download New Data...</guimenuitem></menuchoice>
0460 menu item where you can download catalogs provided by &kstars; team and the community through
0461 the <ulink url="https://invent.kde.org/vboettcher/kstars-catalogs">catalog
0462 packaging repository</ulink>. The <guilabel>DSO minimal zoom:</guilabel>
0463 slider controls the minimal zoom level for which the
0464 DSOs are shown. Increasing the minimal zoom level can lead to
0465 performance improvements when panning the skymap zoomed-out.
0466 The <guilabel>DSO cache percentage:</guilabel> slider regulates how
0467 much of the DSO master catalog is being kept in memory. If you
0468 experience memory issues with large catalogs, try lowering the
0469 percentage. The <guilabel>Label density:</guilabel> slider controls
0470 the perceived density of labels for the DSOs. If labels start to
0471 overlap and the skymap begins to look too crowded, try tuning this
0472 option. The <guilabel>Faint limit zoomed in/out:</guilabel> regulates up to which
0473 magnitude objects are shown on the skymap (higher magnitude is
0474 fainter). If <guilabel>Show objects of unknown magnitude</guilabel> is
0475 ticked, objects of unknown magnitude are always shown.
0476 </para>
0477 <para>The following sections will detail how DSO catalogs work in
0478 &kstars; and how they're managed.</para>
0479 
0480 <sect2 id="catalog_general">
0481 <title>The DSO Catalog Database</title>
0482 <indexterm><primary>Deep-Sky Catalogs</primary>
0483 <secondary>Database</secondary></indexterm>
0484 <indexterm><primary>Deep-Sky Catalogs</primary>
0485   <secondary>Database System</secondary></indexterm>
0486 <note>
0487   <para>
0488     This section aims at introducing the catalog database of &kstars; in
0489     simple but technical terms. It can be skipped without missing anything
0490     essential but helps understanding how to deal with and create (custom)
0491     catalogs.
0492   </para>
0493 </note>
0494 <para>
0495 DSO catalogs  in &kstars; are  just SQL (sqlite3) database  tables. Each
0496 catalog is represented by its own table which contains all its objects
0497 and an entry in a catalog  metadata table. Additionally, catalogs may be
0498 imported or exported from and into stand-alone database  files.
0499 </para>
0500 
0501 <para>
0502 Each object has the usual properties like name and coordinates but
0503 additionally features two IDs. The first ID is the unique identifier
0504 for the specific object and is calculated by hashing all the object fields
0505 along with the catalog id. Because objects can be contained in several
0506 catalogs each object has an additional object id (OID) that identifies
0507 the physical object and may be shared by several objects of different
0508 catalogs.
0509 </para>
0510 
0511 <para>
0512 To speed up object lookup all enabled catalogs are merged into a
0513 master table. Each catalog has a priority number and if several
0514 objects with the same OID occur the one from the catalog with the
0515 highest priority is loaded. The objects from the master catalog are
0516 then drawn on the sky and generally available in &kstars;.
0517 </para>
0518 
0519 <para>
0520 Currently, deduplication (the assignment of OIDs) is only supported by
0521 the tooling of
0522 the <ulink url="https://invent.kde.org/vboettcher/kstars-catalogs">catalog
0523 packaging repository</ulink>. The aim of this tool-chain is to
0524 reproducibly build catalogs in a homogeneous environment. Every
0525 catalog is
0526 implemented <ulink url="https://invent.kde.org/vboettcher/kstars-catalogs/-/blob/master/catalogs/sharpless_2.py">
0527 as a python module</ulink> and provides standard methods to acquire
0528 data, parse it and find duplicates in other catalogs. All
0529 downloadable catalogs are implemented this way. If you'd like to make
0530 a catalog of your own available for &kstars;, it is recommended that you
0531 implement it as a package in the repository. The tooling provided
0532 there is so flexible, that it should work for you. For more
0533 information on how to do that see
0534 the <ulink url="https://protagon.space/catalogs/">catalog repository
0535 documentation</ulink>. If you are not familiar with python programming
0536 you can request the addition of a catalog by opening a ticket in the
0537 repository or
0538 contacting <ulink url="https://invent.kde.org/vboettcher/kstars-catalogs/-/project_members">the
0539 maintainers</ulink>. &kstars; provides also provides means to create
0540 custom catalogs by manually entering data or importing CSV tables, but
0541 those are less flexible and offer no deduplication.
0542 </para>
0543 </sect2>
0544 <sect2 id="catalog_gui">
0545 <title>The Catalog Management &GUI;</title>
0546 <indexterm><primary>Deep-Sky Catalogs</primary>
0547 <secondary>GUI</secondary></indexterm>
0548 <para>
0549 The catalog management &GUI; is reached via the <menuchoice><guimenu>Data</guimenu>
0550 <guimenuitem>Manage DSO Catalogs...</guimenuitem></menuchoice> menu item and is displayed
0551 <link linkend="dso_manager">below</link>.
0552 
0553 <screenshot>
0554 <screeninfo>DSO Manager</screeninfo>
0555 <mediaobject id="dso_manager">
0556   <imageobject>
0557     <imagedata fileref="dso_manager.png" format="PNG"/>
0558   </imageobject>
0559   <textobject>
0560     <phrase>The DSO catalog management interface.</phrase>
0561   </textobject>
0562   <caption>The DSO catalog management interface.</caption>
0563 </mediaobject>
0564 </screenshot>
0565 </para>
0566 <para>
0567 On the left, a list of catalogs is displayed. In this list, you can
0568 read off key catalog properties, including whether a catalog is
0569 enabled, what its ID is and what its name
0570 is. The <guilabel>Mutable</guilabel> column signifies whether the catalog
0571 can be edited or not. Catalogs which have been downloaded from the
0572 catalog repository via the <menuchoice><guimenu>Data</guimenu>
0573 <guimenuitem>Download New Data...</guimenuitem></menuchoice> menu item are
0574 usually immutable whereas user-created catalogs aren't. You can
0575 always <guilabel>Clone</guilabel> a catalog to make it mutable.
0576 </para>
0577 <para>
0578 The buttons in the upper right corner allow you to add catalogs to the
0579 database.
0580 </para>
0581 <variablelist>
0582 <varlistentry id="import">
0583 <term><guibutton>Import Catalog...</guibutton></term>
0584 <listitem>
0585   <para>Import a catalog in the <literal role="extension">.kscat</literal> format
0586   from a file.</para>
0587   <para>This is usually done to try out new versions of catalogs that
0588   haven't yet been picked up by the usual download server.</para>
0589 </listitem>
0590 </varlistentry>
0591 </variablelist>
0592 <para>
0593 With the buttons in the lower right corner, you can add, remove, modify
0594 and explore catalogs. Their actions always refer to the currently
0595 selected catalog (the highlighted row on the left).
0596 
0597 <variablelist>
0598 <varlistentry>
0599 <term><guibutton>Create Catalog...</guibutton></term>
0600 <listitem>
0601   <para>Create a new catalog. See <xref linkend="create_catalog"/>.
0602   </para>
0603 </listitem>
0604 </varlistentry>
0605 
0606 <varlistentry>
0607 <term><guibutton>Enable / Disable</guibutton></term>
0608 <listitem>
0609   <para>Enable or disable a catalog.</para>
0610   <para>This is reflected in the skymap upon closing the
0611     catalog management &GUI;.</para>
0612 </listitem>
0613 </varlistentry>
0614 
0615 <varlistentry>
0616 <term><guibutton>Remove</guibutton></term>
0617 <listitem>
0618   <para>Remove a catalog from the catalog database.</para>
0619   <para>This is reflected in the skymap upon closing the
0620     catalog management &GUI;.</para>
0621 </listitem>
0622 </varlistentry>
0623 
0624 <varlistentry>
0625 <term><guibutton>Export...</guibutton></term>
0626 <listitem>
0627   <para>Export a catalog into a <literal role="extension">.kscat</literal> file.</para>
0628   <para>The resulting file can be imported with 
0629   <link linkend="import"><guibutton>Import Catalog...</guibutton></link> button.
0630   </para>
0631 </listitem>
0632 </varlistentry>
0633 
0634 <varlistentry>
0635 <term><guibutton>Clone...</guibutton></term>
0636 <listitem>
0637   <para>Make an exact copy of the catalog and insert it into the database.</para>
0638   <para>This is useful if you wish to make modifications to an
0639   immutable catalog.
0640     <note><para>Note however that this is not the recommended way to
0641     alter catalogs that are provided by
0642     the <ulink url="https://invent.kde.org/vboettcher/kstars-catalogs">catalog
0643     packaging repository</ulink> &ie; the catalogs downloaded via the
0644     <menuchoice><guimenu>Data</guimenu><guimenuitem>Download New
0645     Data...</guimenuitem></menuchoice> menu item.
0646     </para>
0647     </note>
0648   </para>
0649 </listitem>
0650 </varlistentry>
0651 
0652 <varlistentry>
0653 <term><guibutton>Colors</guibutton></term>
0654 <listitem>
0655   <para>Open the catalog color editor (See <xref linkend="catalog_colors"/>.).
0656   </para>
0657   <para>This will open a dialog which allows you to set the colors in
0658   which objects from the selected catalog will be displayed for each
0659   color scheme.
0660   </para>
0661 </listitem>
0662 </varlistentry>
0663 
0664 <varlistentry>
0665 <term><guibutton>More...</guibutton></term>
0666 <listitem>
0667   <para>Open the catalog details dialog. (See <xref linkend="catalog_details"/>.)
0668   </para>
0669   <para>In there, you can see the contents of the catalog, as well as
0670   some more meta information. Amongst other things, you can also edit
0671   its contents (if it is mutable).
0672   </para>
0673 </listitem>
0674 </varlistentry>
0675 </variablelist>
0676 </para>
0677 </sect2>
0678 
0679 <sect2 id="create_catalog">
0680 <title>Creating a new Catalog</title>
0681 <screenshot>
0682 <screeninfo>Catalog creation dialog</screeninfo>
0683 <mediaobject>
0684   <imageobject>
0685     <imagedata fileref="create_catalog.png" format="PNG"/>
0686   </imageobject>
0687   <textobject>
0688     <phrase>Catalog creation dialog.</phrase>
0689   </textobject>
0690 </mediaobject>
0691 </screenshot>
0692 <para>
0693 This dialog reached through the catalog management &GUI; (see
0694 <xref linkend="catalog_gui"/>). The <guilabel>ID:</guilabel>
0695 field will be automatically chosen but can be
0696 changed. The <guilabel>Color:</guilabel> field configures in which
0697 color the objects of the catalog will be displayed. All the other
0698 values are optional or have sensible defaults. You can, of
0699 course, change these values at a later point.
0700 </para>
0701 
0702 <para>Upon clicking <guilabel>Ok</guilabel> an empty catalog with the
0703   meta data entered into the dialog will be added to the database and
0704   can then be filled with
0705   objects. (See <xref linkend="catalog_details"/> and <xref linkend="csv_import"/>.)
0706 </para>
0707 </sect2>
0708 
0709 <sect2 id="catalog_colors">
0710 <title>Catalog Color Editor</title>
0711 <indexterm><primary>Deep-Sky Catalogs</primary>
0712   <secondary>Catalog Color Editor</secondary></indexterm>
0713 
0714 <screenshot>
0715 <screeninfo>Catalog color editor</screeninfo>
0716 <mediaobject>
0717   <imageobject>
0718     <imagedata fileref="color_editor.png" format="PNG"/>
0719   </imageobject>
0720   <textobject>
0721     <phrase>The catalog color editor.</phrase>
0722   </textobject>
0723 </mediaobject>
0724 </screenshot>
0725 <para>
0726 This dialog reached through the catalog management &GUI; (see
0727 <xref linkend="catalog_gui"/>). Each button represents the color that
0728 objects will be drawn in for a specific color scheme. Clicking on a
0729 button will allow you to choose a color with a color picker. The
0730 button colors are initialized with the default colors from the catalog
0731 specification. The color "default" is the color which will be chosen
0732 for the catalog if there is no color set for a color scheme.
0733 </para>
0734 </sect2>
0735 
0736 <sect2 id="catalog_details">
0737 <title>Catalog Details Dialog</title>
0738 <indexterm><primary>Deep-Sky Catalogs</primary>
0739   <secondary>Catalog Details Dialog</secondary></indexterm>
0740 
0741 <screenshot>
0742 <screeninfo>Catalog details dialog</screeninfo>
0743 <mediaobject>
0744   <imageobject>
0745     <imagedata fileref="catalog_details.png" format="PNG"/>
0746   </imageobject>
0747   <textobject>
0748     <phrase>The catalog details dialog.</phrase>
0749   </textobject>
0750 </mediaobject>
0751 </screenshot>
0752 <para>
0753 This dialog reached through the catalog management &GUI; (see
0754 <xref linkend="catalog_gui"/>). In the top left corner, the catalog
0755 metadata is being displayed. On the right, a table of all objects in
0756 the catalog is being shown. The search line above the table filters
0757 objects by name. Double-clicking a row opens the object details dialog
0758 (see <xref linkend="tool-details"/>).
0759 </para>
0760 <para>
0761 Selecting a row enables
0762 the <guilabel>Object</guilabel> menu on the left.
0763 Selecting multiple rows performs the single-object action for each
0764 selected object.
0765 
0766 <variablelist>
0767 <varlistentry>
0768 <term><guibutton>Edit...</guibutton></term>
0769 <listitem>
0770   <para>Edit the catalog object. (See <xref linkend="add_object"/>).
0771   </para>
0772 </listitem>
0773 </varlistentry>
0774 
0775 <varlistentry>
0776 <term><guibutton>Remove</guibutton></term>
0777 <listitem>
0778   <para>Removes the object from the catalog.
0779   </para>
0780 </listitem>
0781 </varlistentry>
0782 </variablelist>
0783 </para>
0784 
0785 <para>
0786   Below the <guilabel>Object</guilabel> section, the general catalog
0787   options are situated.
0788 
0789 <variablelist>
0790 <varlistentry>
0791     <term><menuchoice>
0792         <guimenu>Edit Catalog Meta...</guimenu>
0793     </menuchoice></term>
0794     <listitem>
0795       <para>Edit the catalog metadata displayed in the top left. This
0796         opens the dialog described in <xref linkend="create_catalog"/>.
0797       </para>
0798     </listitem>
0799   </varlistentry>
0800 
0801   <varlistentry>
0802     <term><guibutton>Add Object...</guibutton></term>
0803     <listitem>
0804       <para>Add an object to the catalog. (See <xref linkend="add_object"/>.)
0805       </para>
0806     </listitem>
0807   </varlistentry>
0808 
0809   <varlistentry>
0810     <term><guibutton>Import CSV...</guibutton></term>
0811     <listitem>
0812       <para>Import objects from a tabular text format (csv, tsv,
0813         &etc;) into the catalog. (See <xref linkend="csv_import"/>.)
0814       </para>
0815     </listitem>
0816   </varlistentry>
0817 </variablelist>
0818 </para>
0819 <sect3 id="add_object">
0820 <title>Adding/Editing Objects</title>
0821 <indexterm><primary>Deep-Sky Catalogs</primary>
0822   <secondary>Adding/Editing Objects</secondary></indexterm>
0823 
0824 <screenshot>
0825   <screeninfo>Add/Edit DSO Dialog</screeninfo>
0826   <mediaobject>
0827     <imageobject>
0828       <imagedata fileref="add_object.png" format="PNG"/>
0829     </imageobject>
0830     <textobject>
0831       <phrase>Add/Edit DSO Dialog</phrase>
0832     </textobject>
0833   </mediaobject>
0834 </screenshot>
0835 <para>
0836   This dialog allows to create or edit a deep sky object
0837   (DSO). The <guilabel>Basics</guilabel> section contains fields that
0838   have to be filled in.
0839 </para>
0840 
0841 <variablelist>
0842   <varlistentry>
0843     <term><guilabel>Name:</guilabel></term>
0844     <listitem><para>The name of the object which will be displayed in the sky.</para></listitem>
0845   </varlistentry>
0846 
0847   <varlistentry>
0848     <term><guilabel>Type:</guilabel></term>
0849     <listitem><para>The type of the object.</para></listitem>
0850   </varlistentry>
0851 
0852   <varlistentry>
0853     <term><guilabel>RA / Dec (°, J2000):</guilabel></term>
0854     <listitem><para>The coordinates of the object in degrees and with respect to the J2000 epoch.</para></listitem>
0855   </varlistentry>
0856 
0857   <varlistentry>
0858     <term><guilabel>Apparent magnitude:</guilabel></term>
0859     <listitem><para>The apparent magnitude of the object.</para></listitem>
0860   </varlistentry>
0861 </variablelist>
0862 
0863 <para>
0864   The <guilabel>Optional</guilabel> section contains data fields that
0865   are optional, is divided into two subsections. They are set to and can be left at their defaults.
0866 </para>
0867 
0868 <para>
0869   The <guilabel>Size Info in Arcminutes</guilabel> subsection. The object is modeled as an ellipse which is described by its major and minor axis.
0870 </para>
0871 
0872 <para>
0873   The <guilabel>Misc</guilabel> subsection.
0874 </para>
0875 
0876 <variablelist>
0877   <varlistentry>
0878     <term><guilabel>Long name:</guilabel></term>
0879     <listitem><para>A longer, more descriptive name.</para>
0880     <para>Usually, the long name is something like <quote>Andromeda Galaxy</quote> for the object M31. It can contain alternative designations and names in other catalogs as well.</para></listitem>
0881   </varlistentry>
0882 
0883   <varlistentry>
0884     <term><guilabel>Catalog identifier:</guilabel></term>
0885     <listitem><para>A catalog internal identifier.</para>
0886     <para>For example the screenshot above, the object originates from the OpenNGC catalog where each row is identified by <quote>NGCXXXX</quote>.</para></listitem>
0887   </varlistentry>
0888 
0889   <varlistentry>
0890     <term><guilabel>Flux:</guilabel></term>
0891     <listitem><para>The flux of the object. Only applies for radio sources.</para></listitem>
0892   </varlistentry>
0893 
0894   <varlistentry>
0895     <term><guilabel>Position angle (°):</guilabel></term>
0896     <listitem><para>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.</para></listitem>
0897   </varlistentry>
0898 </variablelist>
0899 
0900 </sect3>
0901 <sect3 id="csv_import">
0902 <title>Importing CSV (and similar formats)</title>
0903 <screenshot>
0904 <screeninfo>Importing CSV Catalogs</screeninfo>
0905 <mediaobject>
0906   <imageobject>
0907     <imagedata fileref="csv_import.png" format="PNG"/>
0908   </imageobject>
0909   <textobject>
0910     <phrase>Importing CSV Catalogs</phrase>
0911   </textobject>
0912 </mediaobject>
0913 </screenshot>
0914 <para>The screenshot above shows the CSV import dialog in its default
0915   state. In the <guilabel>Input</guilabel> section, you can
0916   configure the csv parser. The <guilabel>Comment prefix:</guilabel> is
0917   the character that signals commented-out lines in the
0918   input. The <guilabel>Separator:</guilabel> should be adjusted to fit
0919   your input. Usually, it is <quote>,</quote> or <quote>;</quote> but other separators can
0920   occur. Finally, you can choose to skip a number of lines at the
0921   beginning of the file. <guibutton>Select/Read</guibutton> button lets you
0922   choose a csv file to read with the above configuration. After that,
0923   the dialog will look as in the screenshot below.
0924 </para>
0925 <screenshot>
0926 <screeninfo>Importing CSV Catalogs, Populated</screeninfo>
0927 <mediaobject>
0928   <imageobject>
0929     <imagedata fileref="csv_import_populated.png" format="PNG"/>
0930   </imageobject>
0931   <textobject>
0932     <phrase>Importing CSV Catalogs</phrase>
0933   </textobject>
0934 </mediaobject>
0935 </screenshot>
0936 <para>
0937 In the top right you can choose whether coordinates are being
0938 expressed in degrees or
0939 hours/minutes/seconds. The <guilabel>Mapping</guilabel> section lets
0940 you map columns in the CSV file to data fields in
0941 &kstars;. Selecting <guilabel>Ignore</guilabel> assigns the default
0942 value for this field. Entering your own text will use this as the
0943 value for every object being read.  The <guilabel>Type
0944 Mapping</guilabel> section maps strings to object types. You can add
0945 and remove mappings by clicking <guilabel>+</guilabel>
0946 or <guilabel>-</guilabel>.  When you're done mapping, you can test
0947 your settings by clicking <guilabel>Preview</guilabel> to read the
0948 first few objects from the csv. If you are satisfied you can
0949 click <guilabel>OK</guilabel> to import the whole catalog or adjust
0950 your settings and preview again. As a reference, a mapping for the
0951 OpenNGC catalog is shown in the below screenshot.
0952 </para>
0953 <screenshot>
0954 <screeninfo>Importing CSV Catalogs, OpenNGC</screeninfo>
0955 <mediaobject>
0956   <imageobject>
0957     <imagedata fileref="csv_openngc.png" format="PNG"/>
0958   </imageobject>
0959   <textobject>
0960     <phrase>Importing CSV Catalogs</phrase>
0961   </textobject>
0962 </mediaobject>
0963 </screenshot>
0964 </sect3>
0965 </sect2>
0966 </sect1>
0967 
0968 <sect1 id="solar_system">
0969 <title>Solar System</title>
0970 <screenshot>
0971 <screeninfo>Solar System Window</screeninfo>
0972 <mediaobject>
0973   <imageobject>
0974     <imagedata fileref="solarsystem_page.png" format="PNG"/>
0975   </imageobject>
0976   <textobject>
0977     <phrase>Solar System Window</phrase>
0978   </textobject>
0979 </mediaobject>
0980 </screenshot>
0981 <para>
0982 <indexterm><primary>Configure &kstars; window</primary>
0983 <secondary>Solar System page</secondary></indexterm>
0984 In the <guilabel>Solar System</guilabel> page, you can specify whether
0985 the Sun, Moon, planets, comets and asteroids are displayed, and
0986 whether the major bodies are drawn as colored circles or actual images.
0987 You can also toggle whether solar system bodies have name labels attached,
0988 and control how many of the comets and asteroids get name labels.
0989 There is an option to automatically attach a temporary <quote>orbit
0990 trail</quote> whenever a solar system body is tracked, and another to
0991 toggle whether the color of the orbit trail fades into the background
0992 sky color.
0993 </para>
0994 </sect1>
0995 
0996 <sect1 id="satellites">
0997 <title>Satellites</title>
0998 <screenshot>
0999 <screeninfo>Satellites Window</screeninfo>
1000 <mediaobject>
1001   <imageobject>
1002     <imagedata fileref="satellites_page.png" format="PNG"/>
1003   </imageobject>
1004   <textobject>
1005     <phrase>Satellites Window</phrase>
1006   </textobject>
1007 </mediaobject>
1008 </screenshot>
1009 <para>
1010 <indexterm><primary>Configure &kstars; window</primary>
1011 <secondary>Satellites page</secondary></indexterm>
1012 The <guilabel>Satellites</guilabel> page allows you to set the satellites view options. Firstly,
1013 you can see or hide the satellites on the skymap using <guilabel>Show satellites</guilabel> checkbox
1014 from the top <guilabel>View Options</guilabel> section. By default, satellites are drawn as small
1015 light red filled circles with an optional dark red name label next to them. You can enable or disable
1016 these labels by checking or not the <guilabel>Show labels</guilabel> checkbox. It is located below
1017 the <guilabel>Show satellites</guilabel> checkbox, within the <guilabel>View Options</guilabel> section.
1018 </para>
1019 <para>
1020 The colors of the dots representing satellites and their name labels can be easily customized using
1021 the <guilabel>Colors</guilabel> page from the same <guilabel>Configure - &kstars;</guilabel> window.
1022 In addition, satellites can be drawn just like regular stars by checking the <guilabel>Draw satellites
1023 like stars</guilabel> checkbox. To display only the visible satellites from your current geographic location
1024 and time, select <guilabel>Show only visible satellites</guilabel>.
1025 </para>
1026 <para>
1027 &kstars; can draw artificial satellites from many predefined groups. Thus, you can select to display a particular
1028 group, multiple groups or partially select subgroups. Under each group, a list of individual satellites is
1029 presented. To select all satellites from a group, you need to check the group checkbox. You can also select
1030 only the satellites of interest in each group.
1031 The satellites orbital elements can be updated via the internet by pressing the <guibutton>Update TLEs</guibutton>
1032 button. Another way for updating the satellites orbital elements is to use the <menuchoice><guimenu>Data</guimenu>
1033 <guisubmenu>Updates</guisubmenu> <guimenuitem>Update Satellites Orbital Elements</guimenuitem></menuchoice> menu
1034 item. If you know the name of a desired satellite then you can use the search satellites method that &kstars;
1035 provides. You need to enter the name of satellite in the <guilabel>Search satellites</guilabel> text box and the
1036 list will be reduced only to its best matches.
1037 </para>
1038 <para>
1039 You can add new satellites to &kstars; default satellites set by editing the
1040 <filename>kstars/data/satellites.dat</filename> file. As each line of this file is a group of
1041 satellites, you need to add a new entry for your desired satellites group.
1042 An entry should have the following format: <userinput>Group Name;local_filename;url</userinput>.
1043 For example: <userinput>Iridium;iridium.tle;https://celestrak.com/NORAD/elements/iridium.txt</userinput>.
1044 </para>
1045 </sect1>
1046 
1047 <sect1 id="supernovae">
1048 <title>Supernovae</title>
1049 <screenshot>
1050 <screeninfo>Supernovae Window</screeninfo>
1051 <mediaobject>
1052   <imageobject>
1053     <imagedata fileref="supernovae_page.png" format="PNG"/>
1054   </imageobject>
1055   <textobject>
1056     <phrase>Supernovae Window</phrase>
1057   </textobject>
1058 </mediaobject>
1059 </screenshot>
1060 <para>
1061 <indexterm><primary>Configure &kstars; window</primary>
1062 <secondary>Supernovae page</secondary></indexterm>
1063 The <guilabel>Supernovae</guilabel> page allows you to decide if the supernovae are displayed or not by checking
1064 the <guilabel>Show supernovae</guilabel> checkbox. By default, supernovae are drawn as small light orange <quote>+</quote> mark.
1065 As for satellites, the color of supernovae can be easily customized using the <guilabel>Colors</guilabel> page.
1066 </para>
1067 <para>
1068 You can set the magnitude limit for showing a supernova as well as magnitude limit for supernova alerts using
1069 the spin boxes control. The limiting magnitude is the faintest apparent magnitude of an skyobject that is
1070 visible with the naked-eye or a telescope.
1071 </para>
1072 <para>
1073 The list of recent supernovae can be updated via the <menuchoice><guimenu>Data</guimenu> 
1074 <guisubmenu>Updates</guisubmenu> <guimenuitem>Update Recent Supernovae data</guimenuitem></menuchoice> menu item.
1075 </para>
1076 </sect1>
1077 
1078 <sect1 id="guides">
1079 <title>Guides</title>
1080 <screenshot>
1081 <screeninfo>Guides Window</screeninfo>
1082 <mediaobject>
1083   <imageobject>
1084     <imagedata fileref="guides_page.png" format="PNG"/>
1085   </imageobject>
1086   <textobject>
1087     <phrase>Guides Window</phrase>
1088   </textobject>
1089 </mediaobject>
1090 </screenshot>
1091 <para>
1092 <indexterm><primary>Configure &kstars; window</primary>
1093 <secondary>Guides page</secondary></indexterm>
1094 The <guilabel>Guides</guilabel> page lets you toggle whether non-objects
1095 are displayed (&ie;, constellation lines, constellation names, the
1096 Milky Way contour, the <link linkend="ai-cequator">celestial
1097 equator</link>, <link linkend="ai-ecliptic">the ecliptic</link>, <link
1098 linkend="ai-horizon">the horizon line</link>, and the opaque ground).
1099 You can also choose a sky culture, whether you would like to see Latin constellation
1100 names, <acronym>IAU</acronym>-standard three-letter abbreviations, or
1101 constellation names using your local language.
1102 </para>
1103 </sect1>
1104 
1105 <sect1 id="terrain">
1106 <title>Terrain</title>
1107 <screenshot>
1108 <screeninfo>Terrain Window</screeninfo>
1109 <mediaobject>
1110   <imageobject>
1111     <imagedata fileref="terrain_page.png" format="PNG"/>
1112   </imageobject>
1113   <textobject>
1114     <phrase>Terrain Window</phrase>
1115   </textobject>
1116 </mediaobject>
1117 </screenshot>
1118 <para>
1119 <indexterm><primary>Configure &kstars; window</primary>
1120 <secondary>Terrain page</secondary></indexterm>
1121 The <guilabel>Terrain</guilabel> page lets you configure whether the terrain (landscape) image will be shown on the skymap.
1122 </para>
1123 <para>
1124 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 <ulink url="https://stellarium.org/landscapes.html">Stellarium</ulink>. The details of image creation are the same.
1125 </para>
1126 <para>
1127 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.
1128 </para>
1129 <para>
1130 Once the image is created, it is possible to upload it via the <guilabel>Terrain</guilabel> 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.
1131 </para>
1132 <para>
1133 Moreover, some speedup options can be configured to achieve the best user experience when rendering the terrain on the sky map.
1134 </para>
1135 <tip>
1136     <para>
1137         You can toggle the terrain overlay on and off using a keyboard shortcut <keycombo>&Ctrl;&Shift;<keycap>T</keycap></keycombo> and the <menuchoice><guimenu>View</guimenu><guimenuitem>Show Terrain</guimenuitem></menuchoice> menu item.
1138     </para>
1139 </tip>
1140 </sect1>
1141 
1142 <sect1 id="colors">
1143 <title>Colors</title>
1144 <screenshot>
1145 <screeninfo>Colors Window</screeninfo>
1146 <mediaobject>
1147   <imageobject>
1148     <imagedata fileref="colors_page.png" format="PNG"/>
1149   </imageobject>
1150   <textobject>
1151     <phrase>Colors Window</phrase>
1152   </textobject>
1153 </mediaobject>
1154 </screenshot>
1155 <para>
1156 <indexterm><primary>Configure &kstars; window</primary>
1157 <secondary>Colors page</secondary></indexterm>
1158 <indexterm><primary>Color Schemes</primary>
1159 <secondary>Customizing</secondary></indexterm>
1160 The <guilabel>Colors</guilabel> page allows you to set the color scheme,
1161 and to define custom color schemes.  The tab is split into two panels:
1162 </para>
1163 <para>
1164 The left panel shows a list of all display items with adjustable
1165 colors.  Click on any item to bring up a color selection window to
1166 adjust its color.  Below the list is the <guilabel>Star color
1167 mode:</guilabel> dropdown box.  By default, &kstars; draws stars with
1168 a <link linkend="ai-colorandtemp">realistic color</link> tint according
1169 to the spectral type of the star.  However, you may also choose to draw
1170 the stars as solid white, black or red circles.  If you are using the
1171 realistic star colors, you can set the saturation level of the star
1172 colors with the <guilabel>Star color intensity:</guilabel> spinbox.
1173 </para>
1174 <para>
1175 The right panel lists the defined color schemes.  There are four
1176 predefined schemes: the <guilabel>Default Colors</guilabel> scheme,
1177 <guilabel>Star Chart</guilabel>, which uses black stars on a white
1178 background, <guilabel>Night Vision</guilabel>, which uses only shades
1179 of red in order to protect dark-adapted vision, and <guilabel>Moonless
1180 Night</guilabel>, a more realistic, dark theme.  Additionally,
1181 you can save the current color settings as a custom scheme by clicking
1182 the <guibutton>Save As...</guibutton> button.  It will prompt
1183 you for a name for the new scheme, and then your scheme will appear in
1184 the list in all future &kstars; sessions.  To remove a custom scheme,
1185 simply highlight it in the list, and press the <guibutton>Remove</guibutton> button.
1186 </para>
1187 </sect1>
1188 
1189 <sect1 id="fits-configure">
1190 <title>FITS</title>
1191 <screenshot>
1192 <screeninfo>FITS Window</screeninfo>
1193 <mediaobject>
1194   <imageobject>
1195     <imagedata fileref="fits_page.png" format="PNG"/>
1196   </imageobject>
1197   <textobject>
1198     <phrase>FITS Window</phrase>
1199   </textobject>
1200 </mediaobject>
1201 </screenshot>
1202 <indexterm><primary>Configure &kstars; window</primary>
1203 <secondary>FITS page</secondary></indexterm>
1204 <para><abbrev>FITS</abbrev> (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 <ulink url="https://en.wikipedia.org/wiki/FITS">corresponding Wikipedia article</ulink>. This page allows you to configure presentation and processing of FITS data in &kstars;.
1205 </para>
1206 <para>
1207     The left panel is for configuring FITS viewer itself.
1208 </para>
1209 <para>
1210 Check the <guilabel>Use FITS viewer</guilabel> item if you want automatically display received images in the FITS Viewer.
1211 </para>
1212 <para>The <guilabel>Single preview tab</guilabel> item is to display all captured FITS images in a single tab instead of multiple tabs
1213 per image. The <guilabel>Single window capture</guilabel> item is to display captured FITS images from all cameras in a single FITS Viewer window
1214 instead of a dedicated window to each camera. The <guilabel>Single window open</guilabel> item is to display opened FITS images in a single FITS Viewer window instead of a
1215 dedicated window to each file and the <guilabel>Independent window</guilabel> item is to make FITS Viewer window independent from &kstars;.
1216 </para>
1217 <para>
1218 The right panel lists processing options. The <guilabel>Auto stretch</guilabel> item is to always apply auto stretch to images in FITS Viewer, <guilabel>Limited resources mode</guilabel> is to enable limited resource mode to turn off any resource-intensive operations, namely: <guilabel>Auto debayer</guilabel> (bayered images will not be debayered; only grayscale images are shown), <guilabel>Auto WCS</guilabel> (World Coordinate System data
1219 will not be processed; WCS maps sky coordinates to image coordinates;
1220 equatorial grid lines, object identification, and telescope slew within an
1221 image are disabled), and <guilabel>3D cube</guilabel> (RGB images will not be
1222 processed; only grayscale images are shown). You can switch off some of these resource-greedy operations separately as well.
1223 </para>
1224 </sect1>
1225 
1226 <sect1 id="indi_page">
1227 <title>INDI</title>
1228 <screenshot>
1229 <screeninfo>INDI Window</screeninfo>
1230 <mediaobject>
1231   <imageobject>
1232     <imagedata fileref="indi_page.png" format="PNG"/>
1233   </imageobject>
1234   <textobject>
1235     <phrase>INDI Window</phrase>
1236   </textobject>
1237 </mediaobject>
1238 </screenshot>
1239 <para>For detailed explanation of the options on the <guilabel>INDI</guilabel>
1240 page see the <link linkend="indi-configure">Configure INDI</link> section.
1241 </para>
1242 </sect1>
1243 
1244 <sect1 id="ekos">
1245 <title>Ekos</title>
1246 <screenshot>
1247 <screeninfo>Ekos Window</screeninfo>
1248 <mediaobject>
1249   <imageobject>
1250     <imagedata fileref="ekos_page.png" format="PNG"/>
1251   </imageobject>
1252   <textobject>
1253     <phrase>Ekos Window</phrase>
1254   </textobject>
1255 </mediaobject>
1256 </screenshot>
1257 <para>
1258 Ekos is an astrophotography suite, a complete astrophotography solution that can control
1259 all INDI devices including numerous telescopes, CCDs, DSLRs, focusers, filters, and a lot more.
1260 Ekos supports highly accurate tracking using online and offline astrometry solver, autofocus
1261 and autoguiding capabilities, and capture of single or multiple images using the powerful
1262 built in sequence manager. For detailed explanation of <guilabel>Ekos</guilabel>,
1263 see the <link linkend="tool-ekos">Ekos section of this manual</link>.
1264 </para>
1265 </sect1>
1266 
1267 <sect1 id="xplanet-configure">
1268 <title>Xplanet</title>
1269 <screenshot>
1270 <screeninfo>Xplanet Window</screeninfo>
1271 <mediaobject>
1272   <imageobject>
1273     <imagedata fileref="xplanet_page.png" format="PNG"/>
1274   </imageobject>
1275   <textobject>
1276     <phrase>Xplanet Window</phrase>
1277   </textobject>
1278 </mediaobject>
1279 </screenshot>
1280 <para>
1281 <ulink url="http://xplanet.sourceforge.net/">Xplanet</ulink> (should be installed separately) is
1282 a solar system planet surface renderer. This page allows you to configure presentation and
1283 processing of <application>Xplanet</application> data in &kstars;.
1284 </para>
1285 </sect1>
1286 
1287 <sect1 id="advanced">
1288 <title>Advanced</title>
1289 <screenshot>
1290 <screeninfo>Advanced Window</screeninfo>
1291 <mediaobject>
1292   <imageobject>
1293     <imagedata fileref="advanced_page.png" format="PNG"/>
1294   </imageobject>
1295   <textobject>
1296     <phrase>Advanced Window</phrase>
1297   </textobject>
1298 </mediaobject>
1299 </screenshot>
1300 <para>
1301 <indexterm><primary>Configure &kstars; window</primary>
1302 <secondary>Advanced page</secondary></indexterm>
1303 The <guilabel>Advanced</guilabel> page provides fine-grained control
1304 over the more subtle behaviors of &kstars;.
1305 </para><para>
1306 <indexterm><primary>Atmospheric Refraction</primary></indexterm>
1307 The <guilabel>Correct for atmospheric refraction</guilabel> checkbox
1308 controls whether the positions of objects are corrected for the effects
1309 of the atmosphere.  Because the atmosphere is a spherical shell, light from
1310 outer space is <quote>bent</quote> as it passes through the atmosphere to
1311 our telescopes or eyes on the Earth's surface.  The effect is largest for
1312 objects near the horizon, and actually changes the predicted rise or set
1313 times of objects by a few minutes.  In fact, when you <quote>see</quote> a
1314 sunset, the Sun's actual position is already well below the horizon;
1315 atmospheric refraction makes it seem as if the Sun is still in the sky.
1316 Note that atmospheric refraction is never applied if you are using
1317 <guilabel>Equatorial coordinates</guilabel>.
1318 </para><para>
1319 <indexterm><primary>Animated Slewing</primary></indexterm>
1320 The <guilabel>Use animated slewing</guilabel> checkbox controls how the
1321 display changes when a new focus position is selected in the map.  By
1322 default, you will see the sky drift or <quote>slew</quote> to the new
1323 position; if you uncheck this option, then the display will instead
1324 <quote>snap</quote> immediately to the new focus position.
1325 </para><para>
1326 <indexterm><primary>Objects in the Sky</primary>
1327 <secondary>Labeling</secondary>
1328 <tertiary>Automatic</tertiary>
1329 </indexterm>
1330 If the <guilabel>Attach label to centered object</guilabel> checkbox is
1331 selected, then a name label will automatically be attached to an object
1332 when it is being tracked by the program.  The label will be removed when
1333 the object is no longer being tracked.  Note that you can also manually
1334 attach a persistent name label to any object with its <link
1335 linkend="popup-menu">popup menu</link>.
1336 </para><para>
1337 <indexterm><primary>Objects in the Sky</primary>
1338 <secondary>Hiding</secondary></indexterm>
1339 There are three situations when &kstars; must redraw the sky display very
1340 rapidly: when a new focus position is selected (and <guilabel>Use
1341 animated slewing</guilabel> is checked), when the sky is dragged with the
1342 mouse, and when the time step is large.  In these situations, the positions
1343 of all objects must be recomputed as rapidly as possible, which can put
1344 a large load on the <abbrev>CPU</abbrev>.  If the <abbrev>CPU</abbrev>
1345 cannot keep up with the demand, then the display will seem sluggish or jerky.
1346 To mitigate this, &kstars; will hide certain objects during these rapid-redraw
1347 situations, as long as the <guilabel>Hide objects while moving</guilabel>
1348 checkbox is selected.  The timestep threshold above which objects will be
1349 hidden is determined by the <guilabel>Also hide if time step larger
1350 than:</guilabel> timestep-spinbox.  You can specify the objects that should
1351 be hidden in the <guilabel>Configure Hidden Objects</guilabel> section.
1352 </para>
1353 </sect1>
1354 
1355 <sect1 id="customize">
1356 <title>Customizing the Display</title>
1357 
1358 <para>
1359 There are several ways to modify the display to your liking.</para>
1360 <itemizedlist>
1361 <listitem><para>
1362 <indexterm><primary>Info Boxes</primary><secondary>Customizing</secondary></indexterm>
1363 <indexterm><primary>Info Boxes</primary><secondary>Shading</secondary></indexterm>
1364 Toggle whether the Info Boxes are drawn in the <menuchoice><guimenu>Settings</guimenu>
1365 <guisubmenu>Info Boxes</guisubmenu></menuchoice> submenu.  In addition, you can
1366 manipulate the three Info Boxes with the mouse.  Each box has additional lines of data
1367 that are hidden by default. You can toggle whether these additional lines are visible
1368 by double-clicking a box to <quote>shade</quote> it.  Also, you can reposition a box by
1369 dragging it with the mouse.  When a box hits a window edge, it will
1370 <quote>stick</quote> to the edge when the window is resized.
1371 </para></listitem>
1372 <listitem><para>
1373 <indexterm><primary>Toolbars</primary><secondary>Customizing</secondary></indexterm>
1374 Toggle whether the Toolbars are drawn in the <menuchoice><guimenu>Settings</guimenu>
1375 <guisubmenu>Toolbars Shown</guisubmenu></menuchoice> submenu.  Like most &kde; toolbars,
1376 they can also be dragged around and anchored on any window edge, or even detached from
1377 the window completely if they are unlocked.
1378 </para></listitem>
1379 <listitem><para>
1380 <indexterm><primary>Color Schemes</primary><secondary>Selecting</secondary></indexterm>
1381 Select a different color scheme in the <menuchoice><guimenu>Settings</guimenu>
1382 <guisubmenu>Color Schemes</guisubmenu></menuchoice> submenu.  There are four predefined
1383 color schemes, and you can define your own in the
1384 <link linkend="config"><guilabel>Configure - &kstars;</guilabel></link> window.
1385 </para></listitem>
1386 <listitem>
1387 <para>
1388 <indexterm><primary>Field-of-View Symbols</primary><secondary>Description</secondary></indexterm>
1389 Choose an <quote>FOV Symbol</quote> using the
1390 <menuchoice><guimenu>Settings</guimenu><guisubmenu>FOV Symbols</guisubmenu></menuchoice>
1391 submenu.  <firstterm>FOV</firstterm> is an acronym for <quote>field-of-view</quote>.
1392 An FOV symbol is drawn at the center of the window to indicate where the display
1393 is pointing.  Different symbols have different angular sizes; you can use a symbol to show
1394 what the view through a particular telescope would look like.  For example, if you choose
1395 the <quote>7x35 Binoculars</quote> FOV symbol, then a circle is drawn on the display that is
1396 9.2 degrees in diameter; this is the field-of-view for 7x35 binoculars.
1397 </para>
1398 <para>
1399 <indexterm><primary>Field-of-View Symbols</primary><secondary>Customizing</secondary></indexterm>
1400 You can define your own FOV symbols (or modify the existing symbols) using the
1401 <guimenuitem>Edit FOV Symbols...</guimenuitem> menu item, which launches the FOV Editor:
1402 </para>
1403 <screenshot>
1404 <screeninfo>Field-of-View Symbols Editor</screeninfo>
1405 <mediaobject>
1406   <imageobject>
1407     <imagedata fileref="fovdialog.png" format="PNG"/>
1408   </imageobject>
1409   <textobject>
1410     <phrase>FOV Symbol Editor</phrase>
1411   </textobject>
1412 </mediaobject>
1413 </screenshot>
1414 
1415 <para>
1416 The list of defined FOV symbols is displayed on the left.  On the right are buttons for
1417 adding a new symbol, editing the highlighted symbol's properties, and removing the
1418 highlighted symbol from the list.  Note that you can even modify or remove the four
1419 predefined symbols (if you remove all symbols, the four defaults will be restored the
1420 next time you start &kstars;).  Below these three buttons is a graphical preview display
1421 showing the highlighted symbol from the list.  When the <guibutton>New...</guibutton> or
1422 <guibutton>Edit...</guibutton> button is pressed, the <guilabel>New FOV Indicator</guilabel>
1423 window is opened:
1424 </para>
1425 
1426 <screenshot>
1427 <screeninfo>New Field-of-View Symbol</screeninfo>
1428 <mediaobject>
1429   <imageobject>
1430     <imagedata fileref="newfov.png" format="PNG"/>
1431   </imageobject>
1432   <textobject>
1433     <phrase>New FOV Symbol</phrase>
1434   </textobject>
1435 </mediaobject>
1436 </screenshot>
1437 
1438 <para>
1439 <indexterm><primary>Field-of-View Symbols</primary><secondary>Defining New</secondary></indexterm>
1440 This window lets you modify the four properties that define a FOV symbol: name, size,
1441 shape, and color.  The angular size for the symbol can either be entered directly in the
1442 <guilabel>Field of View</guilabel> edit box, or you can use the Eyepiece/Camera Tabs to
1443 calculate the field-of-view angle, given parameters of your telescope/eyepiece or
1444 telescope/camera setup.  The five available shapes are: Square, Circle, Crosshairs, Bullseye and Semitransparent circle.
1445 Once you have specified all four parameters, press <guibutton>Ok</guibutton>,
1446 and the symbol will appear in the list of defined symbols.  It will also be available
1447 from the <menuchoice><guimenu>Settings</guimenu><guisubmenu>FOV Symbols</guisubmenu></menuchoice> submenu.
1448 </para>
1449 </listitem>
1450 </itemizedlist>
1451 
1452 </sect1>
1453 
1454 &hips;
1455 
1456 </chapter>