Git commit 3593bd75f994a8399dc501144cc1107d17f8f99c by Hy Murveit. Committed on 09/11/2024 at 01:54. Pushed by murveit into branch 'master'.
Docbook for Imaging Planner M +17 -0 doc/commands.docbook A +183 -0 doc/imagingplanner.docbook A +- -- doc/imagingplanner.png M +1 -0 doc/index.docbook M +2 -0 doc/tools.docbook https://invent.kde.org/education/kstars/-/commit/3593bd75f994a8399dc501144cc1107d17f8f99c diff --git a/doc/commands.docbook b/doc/commands.docbook index c677992166..f238d1a2cf 100644 --- a/doc/commands.docbook +++ b/doc/commands.docbook @@ -587,6 +587,18 @@ color labels and icons to the given positions on the sky chart. </listitem> </varlistentry> +<varlistentry> +<term><menuchoice> +<guimenu>Tools</guimenu> +<guimenuitem>Imaging Planner</guimenuitem> +</menuchoice></term> +<listitem> +<para> +Opens the <link linkend="tool-imaging-planner">Imaging Planner Tool</link>, which helps you find objects to image. +</para> +</listitem> +</varlistentry> + </variablelist> </sect2> @@ -1312,6 +1324,11 @@ Point (straight up).</para></listitem> </para></listitem> </varlistentry> +<varlistentry> +<term><keycombo action="simul">&Ctrl;&Shift;<keycap>P</keycap></keycombo></term> +<listitem><para>Open the Imaging Planner tool.</para></listitem> +</varlistentry> + <varlistentry> <term><keycombo action="simul">&Ctrl;<keycap>R</keycap></keycombo></term> <listitem><para>Run a &kstars; &DBus; script.</para></listitem> diff --git a/doc/imagingplanner.docbook b/doc/imagingplanner.docbook new file mode 100644 index 0000000000..b9d97eee08 --- /dev/null +++ b/doc/imagingplanner.docbook @@ -0,0 +1,183 @@ +<sect1 id="tool-imaging-planner"> +<title>Imaging Planner Tool (experimental)</title> +<indexterm><primary>Tools</primary> +<secondary>Imaging Planner Tool</secondary> +</indexterm> +<screenshot> +<screeninfo> +The Imaging Planner Tool +</screeninfo> +<mediaobject> + <imageobject> + <imagedata fileref="imagingplanner.png" format="PNG"/> + </imageobject> + <textobject> + <phrase>Imaging Planner</phrase> + </textobject> +</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. +</para> +<sect2 id="imagingplanner-objecttable"> +<title>The Object Table</title> +<para> + The left side of the Imaging Planner tool is mostly occupied by the Object Table. It lists all the objects in the loaded catalog, other than those filtered out--see the Filters section below. Attributes of the objects are listed in the columns. Rows can be selected, and the selected row's information, altitude graph and image are shown on the right side of the tool. + </para> + <para>The table defaults to a sort order of more imaging hours on top. However one can change the sort order by clicking on column headers which will sort by that column (with certain secondary column sort defaults). Clicking on the same column header again will reverse the sort order. +</para> + <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 (on 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). +</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> +</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> +</sect2> +<sect2 id="imagingplanner-altitudegraph"> +<title>The Altitude Graph</title> +<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. +</para> +</sect2> + +<sect2 id="imagingplanner-constraints"> +<title>Imaging Constraints</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. +</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 buidings 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. +</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> + The object information section near the top of the left-side of the tool displays information about the selected object. Click on an object and you should see this section filled in. +</para> +<itemizedlist> +<listitem><para> + The top line should display the primary name, object type, and object size on the top line. +</para></listitem><listitem><para>The 2nd line should display any alternate names the object has. +</para></listitem><listitem><para>The 3rd line give transit and moon-separation information. +</para></listitem><listitem><para>The last line allows you to add notes about the object. This information should be stored from session-to-session by KStars in its MySQL database, and is keyed by the object name. You edit these notes by clicking on the pencil icon at the left of the Note line. If you add a upto three URLs in the note (remember to use http or https at the start of the URL) then they should be automatically detected and an icon for browsing those URLs will be added to the Notes line. If the note you add is too long for the line allocated in the Object Information section, you can always see the full note by clicking the editing pencil button. +</para></listitem> +</itemizedlist> +</sect2> +<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 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-filters"> +<title>Filters</title> +<para> + There are a number of ways one can filter the objects displayed in the Imaging Planner's object table. Filtering objects removes them from the table, but they can be accessed again by changing the filter. Note that the filter section can be hidden and exposed by clicking the small button at the left of the filter section. +</para> +<itemizedlist> +<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>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> +</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-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. +</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>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>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>Canera</guimenuitem></menuchoice>, and enter the focal length of your optics and the camera's spedifications. +</para></listitem> +</itemizedlist> +</sect2> +<sect2 id="imagingplanner-catalogs"> +<title>Catalogs</title> +<para> + KStars currently provides a single imaging-planner catalog via the <menuchoice><guimenu>Data</guimenu> <guimenuitem>Download New Data...</guimenuitem></menuchoice> menu item. The hope is that there will be future specialized catalogs, and possibly user-generated catalogs too. Therefore the catalog is formatted in a human-readable way. +</para> +<sect3 id="imagingplanner-catalogs-format"> + <title>Catalog Format</title> +<para> + The format is currently a comma-separated file with one object on a row. +</para> +<itemizedlist> +<listitem><para>The first column is an object ID--which is the kind of ID that would work with the KStars <link linkend="findobjects">Find Object tool</link>. +</para></listitem><listitem><para>The 2nd column is a filename (relative to the catalog's location) where an approximate 300x300 jpeg image of the object can be found. +</para></listitem><listitem><para>The 3rd column is the name of the image's photographer. +</para></listitem><listitem><para>The 4th is a link to a larger version of the image, +</para></listitem><listitem><para>The 5th column is Creative Commons license permission for using the image (e.g. ACC is Attribution Creative Commons, ANCSACC is Attribution Non-Commercial ShareAlike Creative Commons, using the same conventions as the Astrobin.com website). +</para></listitem> +</itemizedlist> +<para> +To add an object without an image, simply add the object ID with no following commas, or an object ID with 4 following commas, such as one of these lines (without quotes): "M 42", or "M 42,,,,". An example full line might be: "M 42,M_42.jpg,Hy Murveit,https://www.astrobin.com/x4dpey/,ACC";. +</para> +<para> +There are a few other possible specialized rows: +</para> +<itemizedlist> + <listitem><para>Rows that start with # are comments.</para></listitem> + <listitem><para>Rows that containt 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> +</sect3> +<sect3 id="imagingplanner-catalogs-loading"> + <title>Loading Catalogs</title> +<itemizedlist> +<listitem><para> + Catalogs read in from <menuchoice><guimenu>Data</guimenu> <guimenuitem>Download New Data...</guimenuitem></menuchoice> are stored in the standard KStars data directory, but catalogs can be read in from anywhere. +</para></listitem><listitem><para> + Use the Imaging Planner's <guibutton>Load Catalog</guibutton> button to read in a new catalog. +</para></listitem><listitem><para> + When a catalog is read in, the previous catalog is discarded. +</para></listitem><listitem><para> + When the tool starts, it reads in the catalog last loaded in the previous session. +</para></listitem> +</itemizedlist> +</sect3> +</sect2> +</sect1> diff --git a/doc/imagingplanner.png b/doc/imagingplanner.png new file mode 100644 index 0000000000..f5e9f2c52a Binary files /dev/null and b/doc/imagingplanner.png differ diff --git a/doc/index.docbook b/doc/index.docbook index 6381e4333a..1b4941ac3f 100644 --- a/doc/index.docbook +++ b/doc/index.docbook @@ -74,6 +74,7 @@ <!ENTITY fitsviewer SYSTEM "fitsviewer.docbook"> <!ENTITY tool-jmoons SYSTEM "jmoons.docbook"> <!ENTITY tool-obsplanner SYSTEM "obsplanner.docbook"> + <!ENTITY tool-imaging-planner SYSTEM "imagingplanner.docbook"> <!ENTITY tool-scriptbuilder SYSTEM "scriptbuilder.docbook"> <!ENTITY tool-solarsys SYSTEM "solarsys.docbook"> <!ENTITY tool-whatsup SYSTEM "wut.docbook"> diff --git a/doc/tools.docbook b/doc/tools.docbook index 3f32c731db..5041792103 100644 --- a/doc/tools.docbook +++ b/doc/tools.docbook @@ -16,6 +16,7 @@ some more advanced aspects of astronomy and the night sky. <listitem><para><link linkend="tool-solarsys">Solar System Viewer</link></para></listitem> <listitem><para><link linkend="tool-jmoons">Jupiter Moons Tool</link></para></listitem> <listitem><para><link linkend="tool-obsplanner">Observation Planner</link></para></listitem> +<listitem><para><link linkend="tool-imaging-planner">Imaging Planner</link></para></listitem> </itemizedlist> &tool-details; @@ -27,5 +28,6 @@ some more advanced aspects of astronomy and the night sky. &tool-solarsys; &tool-jmoons; &tool-obsplanner; +&tool-imaging-planner; </chapter>
