[education/kstars] doc: Update ImagingPlanner docbook
Hy Murveit
null at kde.org
Sat Nov 16 04:42:12 GMT 2024
Git commit 51fb1222048c49aa21d7c5687f6496a8d0268019 by Hy Murveit.
Committed on 16/11/2024 at 02:28.
Pushed by murveit into branch 'master'.
Update ImagingPlanner docbook
M +63 -43 doc/imagingplanner.docbook
M +- -- doc/imagingplanner.png
https://invent.kde.org/education/kstars/-/commit/51fb1222048c49aa21d7c5687f6496a8d0268019
diff --git a/doc/imagingplanner.docbook b/doc/imagingplanner.docbook
index 85c2a39cbe..a9889e467e 100644
--- a/doc/imagingplanner.docbook
+++ b/doc/imagingplanner.docbook
@@ -17,7 +17,7 @@ The Imaging Planner Tool
</mediaobject>
</screenshot>
<para>
- The Imaging Planner tool helps users choose which objects to image. Users can download catalogs of recommended objects, or possibly create and share their own catalogs. The tool computes when the objects in a read-in catalog may be imaged on the selected night given constraints such as minimum altitude, terrain and moon separation. It can sort the objects along several different dimensions including the number of hours an object may be imaged tonight, its peak altitude, distance from the moon, constellation, name and type. Objects can also be filtered out for several reasons (e.g. type of object, whether it was previously imaged, keywords the user has added, whether the object has be selected, user not interested, etc). This tool helps users research the objects by showing small images of the objects, showing the objects' sky locations on the skymap, and by providing links to follow to internet sites with more information and images. It allows users to attach notes and links to objects, and select certain of them for further consideration. This tool can be used in conjection with the Ekos imager or any other imaging tool. It does not currently directly interact with the actual imager; it only helps the user decide what to image.
+ The Imaging Planner tool helps users choose which objects to image. Users can download catalogs of recommended objects, or possibly create and share their own catalogs. The tool computes when the objects in a read-in catalog may be imaged on the selected night given constraints such as minimum altitude, terrain and moon separation. It can sort the objects along several different dimensions including the number of hours an object may be imaged tonight (given the users geography, constraints and possibly artificial horizon), its peak altitude, distance from the moon, constellation, name and type. Objects can also be filtered out for several reasons (e.g. type of object, whether it was previously imaged, keywords the user has added, whether the object has been selected, user not interested, etc). This tool helps users research the objects by showing small images of the objects, showing the objects' sky locations on the skymap, and by providing links to follow to internet sites with more information and images. It allows users to attach notes and links to objects, and select certain of them for further consideration. This tool can be used in conjection with the Ekos imager or any other imaging tool. It does not currently directly interact with the actual imager; it only helps the user decide what to image.
</para>
<sect2 id="imagingplanner-objecttable">
<title>The Object Table</title>
@@ -29,56 +29,42 @@ The Imaging Planner Tool
<para>Right clicking (or control-click) on a row brings up a menu of operations that can be done on the object. Multiple rows can be selected (by the "click then shift-click technique") and the right-click menu may operate on all the selected rows. The operations allow you to add attributes to the object. Choices are:
</para>
<itemizedlist>
-<listitem><para>Pick the object (or un-pick an already picked object). Marking the object as picked will allow you to later just display a few picked objects instead of the whole table. For example, one may spend time researching many objects, and when an interesting candidate is seen, it may be marked picked for later examination. After a while, when a collection of picked objects has been put together, one can only show the picked objects by using the picked filtering constraint (see Filters below).
+<listitem><para>Pick the selected object (or un-pick an already picked object). Note you can select more than one object at a time with click then shift click. Marking an object as picked will allow you to later just display a few picked objects instead of the whole table. For example, one may spend time researching many objects, and when an interesting candidate is seen, it may be marked picked for later examination. After a while, when a collection of picked objects has been put together, one can only show the picked objects by using the picked filtering constraint (see Filters below).
</para></listitem><listitem><para>Mark an object as already imaged (or undo that). Again, one can set this object attribute and later filter for not displaying these (or only displaying those).
</para></listitem><listitem><para>Mark an object to be ignored (or undo that). Similar to marking as already imaged.
+</para></listitem><listitem><para>Center the object on the KStars SkyMap. This mostly makes sense if auto-centering is disable in the Options menu.
</para></listitem>
</itemizedlist>
<para>
Objects that are marked as imaged are displayed with a different background color as the other images in order to distinguish them. This tool doesn't automatically know that you've imaged an object, e.g. because you may have imaged it with KStars/Ekos. Rather you must explicitly mark an object as imaged using the menu, or use the <guibutton>Load Imaged</guibutton> button in the Filters section.
</para>
-<para>The line above the table displays the number of rows in the table and total number of objects in the loaded catalog. They numbers may be different if some objects are filtered out. There is also a search box which will find a certain object in the table.
+<para>
+ Objects that are picked are also displayed differently. They are shown in bold-italic and underlined in order to distinguish them.
+ </para>
+<para>The line above the table displays the number of rows in the table and total number of objects in the loaded catalog. They numbers may be different if some objects are filtered out. There is also a search box which will find a certain object if it is in the table.
</para>
</sect2>
-<sect2 id="imagingplanner-altitudegraph">
-<title>The Altitude Graph</title>
+<sect2 id="imagingplanner-date">
+<title>Date, Time and Geography</title>
+<para>
+ The date for which the analysis is done can be changed by the date input boxes at the top-right of the tool. One can be move back a day by clicking the button on the left of the date, and one can more ahead one day with the button to the right. One can change to an arbitrary date by selected the menu button by the date, or by simply editing the date text. The moon illumination for that day is displayed to the left of the date.
+</para>
<para>
- The currently selected object's altitude is graphed in the Altitude vs Time graph. The graph runs from just before sunset to just after sunrise. You'll notice a dark background during the night. You may also notice a hash-pattern indicating moon illumination in the background. The altitude is graphed in white, but superimposed on top of it is a thicker green line indicating when the object can be imaged given your constraints (see Constraints section below). Thus if you just see a white altitude line, then the object cannot be imaged. If you see a green line, then those are the times and altitudes when the object can be imaged.
+ The time used (e.g. for the object's position in the skymap) and the geography/location used to determine an object's sky position are taken from the values being used in by KStars. To change your location, go to the <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Geographic</guimenuitem></menuchoice> menu. To change the current time, go to the <menuchoice><guimenu>Time</guimenu> <guimenuitem>Set Time...</guimenuitem></menuchoice> menu.
</para>
</sect2>
-
-<sect2 id="imagingplanner-constraints">
-<title>Imaging Constraints</title>
+<sect2 id="imagingplanner-options-help">
+<title>Options and Help</title>
<para>
-The Imaging Planner tool calculates when during the night objects can be imaged. There are several constraints that affect this calculation. Some are set in this tool and a few are KStars/Ekos parameters that may need to be modified.
+There are two buttons to the right of the date control.
</para>
<itemizedlist>
-<listitem><para>The minimum altitude in degrees that an object can be imaged is given in the Min alt box. If you change this value, you should see the Hours column recalculated in the object table and the graph recalculated in the Object Info section.
-</para></listitem><listitem><para>Similar to altitude, you can change the minimum Moon-separation angle in degrees.
-</para></listitem><listitem><para>If the artificial horizon checkbox is checked, then artificial horizon constraints are used to calculate the possible imaging times. The artificial horizon are the parts of the sky that are blocked from imaging by buildings or trees or the like at your telescope's location. The artificial horizon is set up elsewhere in KStars (see <link linkend="settingmenu">Setting Menu</link> and go down to <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Artificial Horizon</guimenuitem></menuchoice>) and at its simplest is a list of azimuth and altitude values. If you make use of this tool and image from an area where significant parts of the sky is blocked, it is recommended you set up and use the artificial horizon feature. Associated with the artificial horizon is the SkyMap's <link linkend="terrain">terrain feature</link>. If you set up your terrain image, then when the Imaging Planner tool displays the object, you will see when it is relative to your local environment. Of course, you'd need to set a realistic imaging time--that is, if you plan during the daytime and the tool is locating objects at the current time, then the object may be set or behind buildings or trees.
-</para></listitem><listitem><para>
- KStars/Ekos uses astronomical twilight times to constrain imaging times. Using the defaults will result in no imaging outside of astronomical twilight times. If you wish to adjust this please see the constraint in the Ekos Scheduler's Offset menu--change the Dusk Offset positive to start imaging later, and negative to start imaging earlier. Similarly change Dawn Offset positive to continue imaging longer, and negative to stop imaging sooner. These controls can be found by selecting <menuchoice><guimenu>Tools</guimenu> <guimenuitem>Ekos</guimenuitem></menuchoice> and then clicking on the Scheduler tab (2nd from the left), clicking the <guibutton>Options</guibutton> button on the bottom right, and the offset tab on the top-left.
+<listitem><para>
+ The options "hamburger" button brings up a small options menu. Currently the menu contains two checkboxes. One controls whether the system slews the KStars SkyMap to an object's coordinates when the object is selected in the table. The second decides if the tool is an independent window (i.e. can go behind or in front of other KStars windows), or if it always goes in front of the main KStars window.
+</para></listitem><listitem><para>The 2nd button, when clicked, brings up this KStars Handbook in a web browser.
</para></listitem>
</itemizedlist>
</sect2>
-<sect2 id="imagingplanner-image">
-<title>Object Image</title>
-<para>
- If it is available, a small image of the currently selected object is displayed. Clicking on the image, astrophotographer credit line, or URL line will browse the given link to a full image if a link was provided.
-</para>
-<para>
- Note that the <guibutton>Load Catalog</guibutton> button is also in this section.
- </para>
-</sect2>
-<sect2 id="imagingplanner-search">
-<title>Image/Object Search</title>
-<para>
- The Search section provides some shortcuts for researching the currently selected object. The <guibutton>Wikipedia</guibutton> button brings up a browser window for Wikipedia using the object's ID. Similar for Simbad. The <guibutton>NGC/IC</guibutton> button brings up a browser window for the Professor Seligman NGC/IC website.
-</para>
-<para>
- The <guibutton>Astrobin</guibutton> button uses the Astrobin.com search facility to perform a slightly more detailed image search. You can cause it search for images in Astrobin with a certain image radius, and require that the result images have won "Astrobin awards" such as top-pick nomination, top-pick or image-of-the-day. Once you browse to the Astrobin website, you can, of course, modify the Astrobin search constraints as you like given the constraints and capabilities of the Astrobin website. The Astrobin search constraints can be hidden and exposed using the button on the left of the Search line.
-</para>
-</sect2>
<sect2 id="imagingplanner-info">
<title>Object Information</title>
<para>
@@ -93,13 +79,33 @@ The Imaging Planner tool calculates when during the night objects can be imaged.
</para></listitem>
</itemizedlist>
</sect2>
-<sect2 id="imagingplanner-date">
-<title>Date, Time and Geography</title>
+<sect2 id="imagingplanner-altitudegraph">
+<title>The Altitude Graph</title>
<para>
- The date for which the analysis is done can be changed by the date input boxes at the top-right of the tool. One can be move back a day by clicking the button on the left of the date, and one can more ahead one day with the button to the right. One can change to an arbitrary date by selected the menu button by the date, or by simply editing the date text. The moon illumination for that day is displayed to the left of the date.
+ The currently selected object's altitude is graphed in the Altitude vs Time graph. The graph runs from just before sunset to just after sunrise. You'll notice a dark background during the night. You may also notice a hash-pattern indicating moon illumination in the background. The altitude is graphed in white, but superimposed on top of it is a thicker green line indicating when the object can be imaged given your constraints (see Imaging Constraints section below). Thus if you just see a white altitude line, then the object cannot be imaged. If you see a green line, then those are the times and altitudes when the object can be imaged. If you click in the graph, you will see the altitude of the selected object displayed in the upper left of the graph.
</para>
+</sect2>
+<sect2 id="imagingplanner-constraints">
+<title>Imaging Constraints</title>
<para>
- The time used (e.g. for the object's position in the skymap) and the geography/location used to determine an object's sky position are taken from the values being used in by KStars. To change your location, go to the <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Geographic</guimenuitem></menuchoice> menu. To change the current time, go to the <menuchoice><guimenu>Time</guimenu> <guimenuitem>Set Time...</guimenuitem></menuchoice> menu.
+The Imaging Planner tool calculates when during the night objects can be imaged. There are several constraints that affect this calculation. Some are set in this tool and a few are KStars/Ekos parameters that may need to be modified.
+</para>
+<itemizedlist>
+<listitem><para>The minimum altitude in degrees that an object can be imaged is given in the Min alt box. If you change this value, you should see the Hours column recalculated in the object table and the graph recalculated in the Object Info section.
+</para></listitem><listitem><para>Similar to altitude, you can change the minimum Moon-separation angle in degrees.
+</para></listitem><listitem><para>If the artificial horizon checkbox is checked, then artificial horizon constraints are used to calculate the possible imaging times. The artificial horizon are the parts of the sky that are blocked from imaging by buildings or trees or the like at your telescope's location. The artificial horizon is set up elsewhere in KStars (see <link linkend="settingmenu">Setting Menu</link> and go down to <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Artificial Horizon</guimenuitem></menuchoice>) and at its simplest is a list of azimuth and altitude values. If you make use of this tool and image from an area where significant parts of the sky is blocked, it is recommended you set up and use the artificial horizon feature. Associated with the artificial horizon is the SkyMap's <link linkend="terrain">terrain feature</link>. If you set up your terrain image, then when the Imaging Planner tool displays the object on the SkyMap, you will see when it is relative to your local environment. Of course, you'd need to set a realistic imaging time--that is, if you plan during the daytime and the tool is locating objects at the current time, then the object may be set or behind buildings or trees.
+</para></listitem><listitem><para>
+ KStars/Ekos uses astronomical twilight times to constrain imaging times. Using the defaults will result in no imaging outside of astronomical twilight times. If you wish to adjust this please see the constraint in the Ekos Scheduler's Offset menu--change the Dusk Offset positive to start imaging later, and negative to start imaging earlier. Similarly change Dawn Offset positive to continue imaging longer, and negative to stop imaging sooner. These controls can be found by selecting <menuchoice><guimenu>Tools</guimenu> <guimenuitem>Ekos</guimenuitem></menuchoice> and then clicking on the Scheduler tab (2nd from the left), clicking the <guibutton>Options</guibutton> button on the bottom right, and the offset tab on the top-left.
+</para></listitem>
+</itemizedlist>
+</sect2>
+<sect2 id="imagingplanner-search">
+<title>Image/Object Search</title>
+<para>
+ The Search section provides some shortcuts for researching the currently selected object. The <guibutton>Wikipedia</guibutton> button brings up a browser window for Wikipedia using the object's ID. Similar for Simbad. The <guibutton>NGC/IC</guibutton> button brings up a browser window for the Professor Seligman NGC/IC website.
+</para>
+<para>
+ The <guibutton>Astrobin</guibutton> button uses the Astrobin.com search facility to perform a slightly more detailed image search. You can cause it search for images in Astrobin with a certain image radius, and require that the result images have won "Astrobin awards" such as top-pick nomination, top-pick or image-of-the-day. Once you browse to the Astrobin website, you can, of course, modify the Astrobin search constraints as you like given the constraints and capabilities of the Astrobin website. The Astrobin search constraints can be hidden and exposed using the button on the left of the Search line.
</para>
</sect2>
<sect2 id="imagingplanner-filters">
@@ -111,28 +117,39 @@ The Imaging Planner tool calculates when during the night objects can be imaged.
<listitem><para>Items can be filtered by how many hours they are image-able this night. Change the value in the <guibutton>Min Hours</guibutton> box, and objects with fewer hours than that value will not be displayed.
</para></listitem><listitem><para>Checking or unchecking one of the object types will cause objects with those types to be displayed or not.
</para></listitem><listitem><para>Picked: Checking Picked will cause only "picked" objects to be displayed. Similarly checking "Not Picked" will cause only objects not picked to be displayed. Checking Don't Care in the picked line will cause the picked-status to be irrelevant in whether an object is filtered from the table.
-</para></listitem><listitem><para>Similar to picked, imaged causes objects labeled as previously imaged to be displayed or not.
+</para></listitem><listitem><para>Similar to picked, Imaged causes objects labeled as previously imaged to be displayed or not.
</para></listitem><listitem><para>Ignored causes objects labeled as "Ignored" to be displayed or not.
-</para></listitem><listitem><para>Keyword searches inside the Notes the user has added to the object, and is "true" if it sees a word in the note that matches the keyword (see the Object-Info section above).
+</para></listitem><listitem><para>Keyword searches inside the Notes the user has added to the object, and is "true" if it sees a word in the note that matches the keyword (see the Object Information section above).
</para></listitem>
</itemizedlist>
<para>
The <guibutton>Load Imaged</guibutton> button in the Imaged row of the Filters section allows you to load an already-imaged file. This file is a simple list of object names, one per row, that you can construct and load. Loading this will cause the tool to remember those object names and mark them as already imaged when it encounters them. If you wish to undo this action, the way to do that is to set the filters to just show imaged objects and then use the right-click/control-click menu to set the desired objects as not imaged. You can speed that up by selecting many objects at a time with the click then shift-click technique.
</para>
</sect2>
+<sect2 id="imagingplanner-image">
+<title>Object Image</title>
+<para>
+ If it is available, a small image of the currently selected object is displayed. Clicking on the image, astrophotographer credit line, or URL line will open a browser with given link to a full image, if a link was provided.
+</para>
+<para>
+ Note that the <guibutton>Load Catalog</guibutton> button is also in this section.
+ </para>
+</sect2>
<sect2 id="imagingplanner-setup">
<title>KStars setup for the Imaging Planner</title>
<para>
- There are a number of ways KStars could be setup to improve the way you experience this tool.
+ There are a number of ways KStars could be setup to improve your experience with this tool.
</para>
<itemizedlist>
<listitem><para>The most important thing to do is go to <menuchoice><guimenu>Data</guimenu> <guimenuitem>Download New Data...</guimenuitem></menuchoice> and download a catalog associated with this tool. The first time you use this tool you'll need to click on the Load Catalog button and load the downloaded catalog. The tool should automatically download the catalog in subsequent runs.
-</para></listitem><listitem><para>Read the Imaging Constraints section below and follow suggestions there, so that this tool can better predict how long an object can be imaged during the date selected.
-</para></listitem><listitem><para>Selected objects are automatically centered in the SkyMap display. If that display is useful, you may want to adjust the zoom so that it is close to your imager's field of view. The items below also apply to that SkyMap display.
+</para></listitem><listitem><para>Another important thing to do, also in the above <menuchoice><guimenu>Data</guimenu> <guimenuitem>Download New Data...</guimenuitem></menuchoice> menu, is to download some deep-sky object catalogs. In particular the NGC IC, OpenNGC, Sharpless, Abell, Lynds and Hickson catalogs would be handy. You can run the Imaging Planner without these (small) downloads, but the start-up time on the first time you use this tool will be much longer if you don't download them.
+</para></listitem><listitem><para>Read the Imaging Constraints section above and follow suggestions there, so that this tool can better predict how long an object can be imaged during the date selected.
+</para></listitem><listitem><para>Selected objects can be automatically centered in the SkyMap display. If that display is useful, you may want to adjust the zoom so that it is close to your imager's field of view. The items below also apply to that SkyMap display.
</para></listitem><listitem><para>You may also want to set the time in KStars to reflect when you'll be imaging. See the Time menu.
</para></listitem><listitem><para>If you don't set the time, you may want to hide the terrain display (if you've set that up) and also not render the ground, as those may obscure the object. You show and hide the terrain display in the view menu, and the ground can be disabled in <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Guides</guimenuitem></menuchoice> with the Opaque Ground checkbox.
-</para></listitem><listitem><para>If you're using a HiPS-based skymap, you would likely want local copies of the DSS data to speed-up the rendering of the SkyMap. See <menuchoice><guimenu>View</guimenu> <guimenuitem>HiPS All Sky Survey</guimenuitem></menuchoice> and under there <menuchoice><guimenu>HiPS Settings...</guimenu> <guimenuitem>Cache</guimenuitem></menuchoice> and enable the cache and enter the location of your local copy of the data. To download the data, one resource is https://coochey.net/?p=699
+</para></listitem><listitem><para>If you're using a HiPS-based skymap, you would likely want local copies of the DSS data to speed-up the rendering of the SkyMap. See <menuchoice><guimenu>View</guimenu> <guimenuitem>HiPS All Sky Survey</guimenuitem></menuchoice> and under there <menuchoice><guimenu>HiPS Settings...</guimenu> <guimenuitem>Cache</guimenuitem></menuchoice> and enable the cache and enter the location of your local copy of the data. The data is available on https://irsa.ipac.caltech.edu/data/hips/CDS/DSS2/color/Norder1 ... /Norder7 and another resource is https://coochey.net/?p=699
</para></listitem><listitem><para>It would be useful to create a custom SkyMap "FOV Symbol" which is the same as the field-of-view of your imager. See <menuchoice><guimenu>Settings</guimenu> <guimenuitem>FOV Symbols</guimenuitem></menuchoice>, and inside there select <menuchoice><guimenu>New</guimenu> <guimenuitem>Camera</guimenuitem></menuchoice>, and enter the focal length of your optics and the camera's specifications.
+</para></listitem><listitem><para>You may want to adjust the color theme, e.g. in <menuchoice><guimenu>Settings</guimenu> <guimenuitem>Themes</guimenuitem></menuchoice> to Black Body if you like dark themes.
</para></listitem>
</itemizedlist>
</sect2>
@@ -164,6 +181,9 @@ There are a few other possible specialized rows:
<listitem><para>Rows that start with # are comments.</para></listitem>
<listitem><para>Rows that contain LoadCatalog RELATIVE_CATALOG_FILENAME mean that the contents of RELATIVE_CATALOG_FILENAME should be read in as if they were in this catalog file.</para></listitem>
</itemizedlist>
+<para>
+If you wanted to add your own objects to the existing catalog, you could do so by creating your own catalog, say on your desktop in a .csv file, and having the first line include the existing catalog with a LoadCatalog line, and having subsequent lines list your new objects. You'd then run Load Catalog on your new .csv file.
+</para>
</sect3>
<sect3 id="imagingplanner-catalogs-loading">
<title>Loading Catalogs</title>
diff --git a/doc/imagingplanner.png b/doc/imagingplanner.png
index f5e9f2c52a..3229a9b01f 100644
Binary files a/doc/imagingplanner.png and b/doc/imagingplanner.png differ
More information about the kde-doc-english
mailing list