[education/kstars] doc: Update handbook fitsviewer section and add new fitsviewer solver section.
Hy Murveit
null at kde.org
Sat Oct 21 01:44:49 BST 2023
Git commit e575f8f5016addf85ea91ca4db5fbfb6e96eef01 by Hy Murveit.
Committed on 21/10/2023 at 02:09.
Pushed by murveit into branch 'master'.
Update handbook fitsviewer section and add new fitsviewer solver section.
M +41 -0 doc/config.docbook
A +- -- doc/developer_page.png
A +- -- doc/fitsviewer-magnifier.png
A +- -- doc/fitsviewer-mark-stars.png
A +- -- doc/fitsviewer-selection.png
A +- -- doc/fitsviewer-solver.png
A +- -- doc/fitsviewer-status.png
A +- -- doc/fitsviewer-stretch.png
M +176 -99 doc/fitsviewer.docbook
A +- -- doc/fitsviewer1.png
A +- -- doc/fitsviewer2.png
https://invent.kde.org/education/kstars/-/commit/e575f8f5016addf85ea91ca4db5fbfb6e96eef01
diff --git a/doc/config.docbook b/doc/config.docbook
index b7e6e1102f..e31a2393e7 100644
--- a/doc/config.docbook
+++ b/doc/config.docbook
@@ -1478,6 +1478,47 @@ be hidden in the <guilabel>Configure Hidden Objects</guilabel> section.
</para>
</sect1>
+<sect1 id="developer">
+<title>Developer</title>
+<screenshot>
+<screeninfo>Developer Window</screeninfo>
+<mediaobject>
+ <imageobject>
+ <imagedata fileref="developer_page.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Developer Window</phrase>
+ </textobject>
+</mediaobject>
+</screenshot>
+<para>
+<indexterm><primary>Configure &kstars; window</primary>
+<secondary>Developer page</secondary></indexterm>
+The <guilabel>Developer</guilabel> page provides a few checkboxes that can help
+debug issues with &kstars;. There are checkboxes for saving images
+in logging directories that might help debug issues. Of course, saving images
+can take up disk space and should be used judiciously.
+</para><para>
+ The images that can be saved are
+ <itemizedlist>
+<listitem><para>
+ all focus images,
+</para></listitem>
+<listitem><para>
+ all guider images,
+</para></listitem>
+<listitem><para>
+ all align images, and
+</para></listitem>
+<listitem><para>
+ align images where the plate-solving failed.
+</para></listitem>
+ </itemizedlist>
+ The images are all saved in folders parallel to the main
+ logging directory. They are in folders named guide, autofocus, align, and align/failed.
+</para>
+</sect1>
+
<sect1 id="customize">
<title>Customizing the Display</title>
diff --git a/doc/developer_page.png b/doc/developer_page.png
new file mode 100644
index 0000000000..a717b79094
Binary files /dev/null and b/doc/developer_page.png differ
diff --git a/doc/fitsviewer-magnifier.png b/doc/fitsviewer-magnifier.png
new file mode 100644
index 0000000000..8968123cc6
Binary files /dev/null and b/doc/fitsviewer-magnifier.png differ
diff --git a/doc/fitsviewer-mark-stars.png b/doc/fitsviewer-mark-stars.png
new file mode 100644
index 0000000000..0c64b89e80
Binary files /dev/null and b/doc/fitsviewer-mark-stars.png differ
diff --git a/doc/fitsviewer-selection.png b/doc/fitsviewer-selection.png
new file mode 100644
index 0000000000..76dcd32c23
Binary files /dev/null and b/doc/fitsviewer-selection.png differ
diff --git a/doc/fitsviewer-solver.png b/doc/fitsviewer-solver.png
new file mode 100644
index 0000000000..15df6064bc
Binary files /dev/null and b/doc/fitsviewer-solver.png differ
diff --git a/doc/fitsviewer-status.png b/doc/fitsviewer-status.png
new file mode 100644
index 0000000000..183fcc279f
Binary files /dev/null and b/doc/fitsviewer-status.png differ
diff --git a/doc/fitsviewer-stretch.png b/doc/fitsviewer-stretch.png
new file mode 100644
index 0000000000..3313d59a37
Binary files /dev/null and b/doc/fitsviewer-stretch.png differ
diff --git a/doc/fitsviewer.docbook b/doc/fitsviewer.docbook
index 5011a7357f..f3b52babbb 100644
--- a/doc/fitsviewer.docbook
+++ b/doc/fitsviewer.docbook
@@ -4,10 +4,9 @@
<secondary>FITS Viewer</secondary>
</indexterm>
-<para>The Flexible Image Transport System (FITS) is the standard format for representing images and data in Astronomy.</para>
+<para>FITS, or Flexible Image Transport System, is the standard format for representing images and data in Astronomy. The &kstars; FITS Viewer is a tool to view those images. It is not designed for editing of FITS Images.</para>
-<para>The &kstars; FITS Viewer tool is automatically invoked when new images are received from the camera.
-It is primarily used to view and examine FITS data. It is not designed for editing of FITS Images.
+<para>The FITS Viewer can be automatically invoked for images received from the camera. It can also be invoked directly from the main &kstars; menu.
To open a FITS file, select the <menuchoice><guimenu>File</guimenu>
<guimenuitem>Open Image...</guimenuitem></menuchoice> menu item, or press
<keycombo action="simul">&Ctrl;<keycap>O</keycap></keycombo>.</para>
@@ -16,7 +15,7 @@ To open a FITS file, select the <menuchoice><guimenu>File</guimenu>
<screeninfo>The FITS Viewer Tool</screeninfo>
<mediaobject>
<imageobject>
- <imagedata fileref="fitsviewer.png" format="PNG"/>
+ <imagedata fileref="fitsviewer1.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>FITS Viewer Tool</phrase>
@@ -24,7 +23,24 @@ To open a FITS file, select the <menuchoice><guimenu>File</guimenu>
</mediaobject>
</screenshot>
-<para>The above diagram illustrates the FITS Viewer work area and window. The tool provides basic functions for image display. FITS data depth is preserved throughout all processing, open, and save functions. While the tool adhere to the FITS standard, it does not support all possible FITS features:</para>
+<para>The above diagram illustrates the FITS Viewer main work area and window. There is also a hidden area that can be exposed by moving the mouse over the 6 small dots on the left side (about center of the image vertically) and pressing and holding the mouse, sliding it over to the right a bit.</para>
+
+<screenshot>
+ <screeninfo>The FITS Viewer Tool with sliding panel open</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="fitsviewer2.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>FITS Viewer Tool with sliding panel open</phrase>
+ </textobject>
+ </mediaobject>
+</screenshot>
+
+<sect2 id="fits-viewer-main-controls">
+ <title>Main Controls</title>
+
+<para>The various controls and displays for the FITS Viewer are shown below. The tool provides basic functions for image display. While the tool adhere to the FITS standard, it does not support all possible FITS features:</para>
<itemizedlist>
<listitem><para>Support for only <emphasis>one</emphasis> image per file.</para></listitem>
<listitem><para>Support for only 2D and 3D data. 1D data are discarded.</para></listitem>
@@ -35,7 +51,7 @@ To open a FITS file, select the <menuchoice><guimenu>File</guimenu>
<itemizedlist>
<listitem><para>File</para>
<itemizedlist>
- <listitem><para>Standard Open, Save, and Save As actions.</para></listitem>
+ <listitem><para>Standard Open, Save, and Save As.</para></listitem>
<listitem><para>FITS Header: Display FITS header table data.</para></listitem>
<listitem><para>Debayer: Covert RAW image to RGB.</para></listitem>
</itemizedlist>
@@ -52,6 +68,7 @@ To open a FITS file, select the <menuchoice><guimenu>File</guimenu>
<listitem><para>Zoom Controls: Zoom in, Zoom out, standard Zoom.</para></listitem>
<listitem><para>Filters: Auto Stretch, Contrast, High Pass, Rotate, Flip.</para></listitem>
<listitem><para>Mark Stars: Detect and mark stars in the image.</para></listitem>
+ <listitem><para>Show Clipping: Display in red which stars have pixels that appear to be clipped.</para></listitem>
</itemizedlist>
</listitem>
</itemizedlist>
@@ -73,6 +90,8 @@ To open a FITS file, select the <menuchoice><guimenu>File</guimenu>
<listitem><para>Flip Vertical.</para></listitem>
<listitem><para>Show Cross Hairs: Toggles crosshairs in the center of the image.</para></listitem>
<listitem><para>Show Pixel Gridlines: Toggles pixel grid.</para></listitem>
+ <listitem><para>Mark Stars: Detect and mark stars in the image.</para></listitem>
+ <listitem><para>Show Clipping: Display in red which stars have pixels that appear to be clipped.</para></listitem>
<listitem><para>Show Equatorial Gridlines: Toggles Equatorial Grid if FITS contains a valid WCS header.</para></listitem>
<listitem><para>Show Objects in Image: Identifies objects such as stars, galaxies, and nebulae within the image.</para></listitem>
<listitem><para>Center Telescope: Toggle Center Telescope mode. When active and if the image contains a valid WCS header, clicking anywhere in the image triggers the telescope slewing to the clicked point.</para></listitem>
@@ -85,20 +104,103 @@ To open a FITS file, select the <menuchoice><guimenu>File</guimenu>
<listitem><para>Side Panel: The side panel can be opened by dragging the separator to the right. When dragged to the left, the side panel can also be closed.</para>
<itemizedlist>
<listitem><para>Statistics: Displays image statistics including Minimum, Maximum, Average, and Median values.</para></listitem>
- <listitem><para>Histogram: Displays image histogram with controls to adjust the minimum and maximum values for each channel. Both linear and logarithmic scalings are available to apply to the image.</para></listitem>
+ <listitem><para>Plate Solving: A tool plate-solve the loaded image. This is useful to debug plate-solving issues.</para></listitem>
+ <listitem><para>Histogram: Displays image histogram with controls to adjust the minimum and maximum values for each channel. Both linear and logarithmic scalings are available to apply to the image. This is somewhat redundant with the below-image histogram and may be removed in the future.</para></listitem>
<listitem><para>FITS Header: Displays a table for FITS header keywords, values, and comments.</para></listitem>
<listitem><para>Recent Images: Displays recently opened images. Clicking on any image will load it.</para></listitem>
</itemizedlist>
</listitem>
- <listitem><para>Image Display Area. Hovering over the image will update the status bar values accordingly.</para>
+ <listitem><para>Image Display Area.</para>
+ <itemizedlist>
+ <listitem><para>Mouse: Hovering over the image will update the status bar values accordingly.</para></listitem>
+ <listitem><para>Mouse: Hovering over the image will move a cursor in the histogram display below the image, if that histogram is activated.</para></listitem>
+ <listitem><para>Control key: Holding down the control key and then moving the mouse will show a magnified portion of the image.</para>
+<screenshot>
+ <screeninfo>The Magnifier in the FITS Viewer</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="fitsviewer-magnifier.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>The magnifier in the FITS Viewer</phrase>
+ </textobject>
+ </mediaobject>
+</screenshot>
+ </listitem>
+ <listitem><para>Statistics of region of interest</para>
+ <para>
+ Provides simple statistics average mean, average standard deviation and average median of the selected region by the user in a tooltip.
+ </para>
+ <screenshot>
+ <screeninfo>
+ FITSViewer
+ </screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="fitsviewer_selstat.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>Selection Statistics</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ <para>
+ The user can either set the selection region by <keycombo>&Shift;<keycap>Left Click</keycap></keycombo> dragging (when the selection statistics is activated) or by choosing an entry from the drop down menu of the Toggle Selection Rectangle button. In addition to this, the user can translate the region by simple <keycap>Left Click</keycap> drag of the mouse. The statistics of the region are shown as a tooltip once the cursor is brought over the selection region. For smaller images, the statistics are updated instantly, and for larger images, the statistics are updated once the user releases the <keycap>Left Click</keycap> button after modification of the region.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>Stretching Controls.
+<screenshot>
+ <screeninfo>The Stretch Controls in the FITS Viewer</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="fitsviewer-stretch.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>The Stretch Controls in the FITS Viewer</phrase>
+ </textobject>
+ </mediaobject>
+</screenshot>
+<para>Near the bottom of the window are controls for stretching the image and displaying its histogram. They are discribed below from left to right.</para>
+ <itemizedlist>
+ <listitem><para>Enable Stretching: On the very left of this display is a button that enables or disables stretching.</para></listitem>
+ <listitem><para>Shadow Value: The value below which pixels are displayed as black can be manually entered (scale is 0 to 1.0, even for integer pixel values).</para></listitem>
+ <listitem><para>Midtones Value: The midtones value which controls the brightness of the iamge can be manually entered (scale is 0 to 1.0, even for integer pixel values).</para></listitem>
+ <listitem><para>Highlights Value: The value above which pixels are displayed as white can be manually entered (scale is 0 to 1.0, even for integer pixel values).</para></listitem>
+ <listitem><para>Show Histogram: A button that displays or hides the image histogram is to the right of the highlights number box.</para></listitem>
+ <listitem><para>Auto Stretch: A button (magic wand icon) that will automatically create a pleasing stretch is found on the right. It is disabled if the stretch is already at the automatically computed value.</para></listitem>
+ </itemizedlist>
+ <para>
+ In addition, there are sliders that can be used to adjust the Shadow, Midtones and Highlights values. Adjusting them will change the values displayed.
+ </para>
+ <para>
+ The histogram, if it is enabled, may be zoomed by using the mouse's scroll wheel, and panned by dragging with the mouse. A cursor in the histogram shows the position of the pixel in the image under the mouse.
+ </para>
</listitem>
- <listitem><para>Status Bar: From right to left, the following status indicators are available:</para>
+ <listitem>Status Bar
+<screenshot>
+ <screeninfo>The Status Display in the FITS Viewer</screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="fitsviewer-status.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>The Status Display in the FITS Viewer</phrase>
+ </textobject>
+ </mediaobject>
+</screenshot>
+<para> From right to left, the following status indicators are available:</para>
<itemizedlist>
<listitem><para>Loading Indicator: The LED becomes yellow when an image is getting loaded and turns green after loading is successfully done. If there are problems with loading the image, it turns red.</para></listitem>
- <listitem><para>Resolution: Image resolution in pixels.</para></listitem>
- <listitem><para>Cartesian Coordinates: Displays and updates the current mouse position as you hover over the image. It include the X and Y position in addition to the current value.</para></listitem>
- <listitem><para>Equatorial Coordinates: If the image contains a valid WCS header, the J2000 Right Ascension (RA) and declination (DE) values are displayed.</para></listitem>
- </itemizedlist>
+ <listitem><para>Resolution: Image resolution in pixels. 4656x3520 in the screenshot above.</para></listitem>
+ <listitem><para>Zoom Percentage. 13% above.</para></listitem>
+ <listitem><para>Cartesian Coordinates: Displays and updates the current mouse position as you hover over the image. X:769 Y:3508 above.</para></listitem>
+ <listitem><para>Pixel Value: Value of the pixel under the mouse. 1,792 above.</para></listitem>
+ <listitem><para>Equatorial Coordinates: If the image contains a valid WCS header, the J2000 Right Ascension (RA) and declination (DE) values are displayed. 13h 14' 22" 42 37' 35" above.</para></listitem>
+ <listitem><para>Image Stats: Displays the HFR, Eccentricity and number of stars if computed. HFR:1.96 Ecc:0.43 143 stars above.</para></listitem>
+ <listitem><para>Clipped Stars: If Show Clipping is activated in the main toolbar, it displays the number of possibly clipped pixels. Clip:403 above.</para></listitem>
+ </itemizedlist>
</listitem>
</orderedlist>
<para>
@@ -129,70 +231,9 @@ To open a FITS file, select the <menuchoice><guimenu>File</guimenu>
<para>
Hovering over any option shall display a detailed tooltip that explains its function.
</para>
+</sect2>
<sect2 id="fits-viewer-features">
<title>Features</title>
- <itemizedlist>
- <listitem>
- <para>
- Support for 8, 16, 32, IEEE-32, and IEEE-64 bits formats.
- </para>
- </listitem>
- <listitem>
- <para>
- Support Color FITS images (3D Cubes) and Bayered FITS images.
- </para>
- </listitem>
- <listitem>
- <para>
- Histogram with linear, logarithmic, and square-root scales.
- </para>
- </listitem>
- <listitem>
- <para>
- Brightness/Contrast controls.
- </para>
- </listitem>
- <listitem>
- <para>
- Pan and Zoom.
- </para>
- </listitem>
- <listitem>
- <para>
- Auto levels.
- </para>
- </listitem>
- <listitem>
- <para>
- Statistics.
- </para>
- </listitem>
- <listitem>
- <para>
- Statistics for a region of interest(Rectangle).
- </para>
- </listitem>
- <listitem>
- <para>
- Rectangular and Equatorial Grids (if WCS info is present).
- </para>
- </listitem>
- <listitem>
- <para>
- Detection and highlight of stars.
- </para>
- </listitem>
- <listitem>
- <para>
- FITS header query.
- </para>
- </listitem>
- <listitem>
- <para>
- Undo/Redo.
- </para>
- </listitem>
- </itemizedlist>
<variablelist>
<varlistentry>
<term>Histogram</term>
@@ -231,33 +272,69 @@ To open a FITS file, select the <menuchoice><guimenu>File</guimenu>
</para>
</listitem>
</varlistentry>
- <varlistentry>
- <term>Statistics of region of interest</term>
- <listitem>
- <screenshot>
- <screeninfo>
- FITSViewer
- </screeninfo>
- <mediaobject>
- <imageobject>
- <imagedata fileref="fitsviewer_selstat.png" format="PNG"/>
- </imageobject>
- <textobject>
- <phrase>Selection Statistics</phrase>
- </textobject>
- </mediaobject>
- </screenshot>
- <para>
- Provides simple statistics average mean, average standard deviation and average median of the selected region by the user in a tooltip.
- </para>
- <para>
- The user can either set the selection region by <keycombo>&Shift;<keycap>Left Click</keycap></keycombo> dragging or by choosing an entry from the drop down menu of the Toggle Selection Rectangle button. In addition to this, the user can translate the region by simple <keycap>Left Click</keycap> drag of the mouse. The statistics of the region are shown as a tooltip once the cursor is brought over the selection region. For smaller images, the statistics are updated instantly, and for larger images, the statistics are updated once the user releases the <keycap>Left Click</keycap> button after modification of the region.
- </para>
- </listitem>
- </varlistentry>
</variablelist>
</sect2>
+<sect2 id="fits-viewer-solver">
+ <title>FITS Viewer Solver</title>
+ <screenshot>
+ <screeninfo>
+ FITS Viewer Solver
+ </screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="fitsviewer-solver.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>FITS Viewer Solver</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ <para>
+ The FITS Viewer Solver is used to plate-solve the image loaded in the FITS Viewer's tab. It only works with the internal StellarSolver. You get the RA and DEC coordinates for the center of the image, the image's scale, the angle of rotation, and the number of stars detected in the image. Its main use case is debugging plate-solving issues in Ekos, though the information displayed can be generally useful. The controls and displays are described below.
+ </para>
+ <itemizedlist>
+ <listitem><para>Solve Button. Pressing this button starts plate solving. When the system is plate solving, the button becomes an abort button.</para></listitem>
+ <listitem><para>Scale: Checking the Use Scale checkbox constains the solver to use approximately the pixel or image scale given. The scale is entered in the box and the units for the scale can be chosen from image width in degrees, image width in arc-minutes, and arc-seconds per pixel. When a solve successfully completes, it replaces the value in the box with solution's scale.</para></listitem>
+ <listitem><para>Position: Checking the Use Position checkbox constains the solver to search near the RA and DEC coordinates given. The extent of the search is given by the user in the Radius box in degrees. Note that RA is input in hours-minutes-seconds, e.g. 13h, and DEC is input in degrees-minutes-seconds, e.g. 85. When a solve successfully completes, it replaces the value in the RA and DEC boxes with solution's coordinates. In addition it fills in the Angle field with the solutions angle value in degrees.</para></listitem>
+ <listitem><para>Use SkyMap Position: There is a button just below the Use Position checkbox that fills in RA and DEC boxes with the current center of the SkyMap display.</para></listitem>
+ <listitem><para>Profile: The Profile menu selects which StellarSolver preset, among those used in the Ekos Align module, should be used for plate solving. This is further discussed below.</para></listitem>
+ <listitem><para>Solution: The Solution section will display the number of stars found and the time taken to solve. The solution values for RA, DEC, Scale and Angle are displayed in those boxes above.</para></listitem>
+ <listitem><para>Image: For any image where stars were detected, if the Mark Stars button is activated above the image display,
+ <screenshot>
+ <screeninfo>
+ FITS Viewer Mark Stars Button
+ </screeninfo>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="fitsviewer-mark-stars.png" format="PNG"/>
+ </imageobject>
+ <textobject>
+ <phrase>FITS Viewer Mark Stars Button</phrase>
+ </textobject>
+ </mediaobject>
+ </screenshot>
+ then the detected stars are circled in red.
+ </para></listitem>
+ </itemizedlist>
+ <para>
+ Using this tool the user can try and debug solving issues as follows.
+ </para>
+ <itemizedlist>
+ <listitem><para>He/she might have the KStars -> Settings -> Developer -> <link linkend="developer">Save Failed Align Images checkbox</link> enabled.</para></listitem>
+ <listitem><para>Then a difficult image (for whom alignment failed) <link linkend="developer">could be located</link> and loaded into the fitsviewer.</para></listitem>
+ <listitem><para>The image could be inspected to see if there were obvious visual issues.</para></listitem>
+ <listitem><para>Clicking Solve in this tool for that image would show how many stars were detected, and the user could then decide if it is a star detection issue and experiment with adjusting the profile or star-detection parameters.
+</para></listitem>
+ <listitem><para>The user could manually upload the image to astrometry.net to get scale and position values (or just see if it is a problematic image).
+</para></listitem>
+ <listitem><para>The user could experiment with Use Position and Use Scale, using accurate values for those constraints (or disabling them) to see if those were the problem, or adjust the parameters in the align profile being used.</para></listitem>
+ </itemizedlist>
+ <para>
+ To inspect or modify the profile, the user would open the align tab in Ekos, go to the Options menu, select the StellarSolver Options tab, make sure the right Options profile is selected, and click the pencil to view or edit that profile.
+ </para>
+</sect2>
+
<sect2 id="fits-viewer-embedded">
<title>Embedded FITS Viewer</title>
<screenshot>
diff --git a/doc/fitsviewer1.png b/doc/fitsviewer1.png
new file mode 100644
index 0000000000..1b9d31e6dc
Binary files /dev/null and b/doc/fitsviewer1.png differ
diff --git a/doc/fitsviewer2.png b/doc/fitsviewer2.png
new file mode 100644
index 0000000000..ab8c0b3b59
Binary files /dev/null and b/doc/fitsviewer2.png differ
More information about the kde-doc-english
mailing list