#########################################################################
#   Sky Monitor for Subaru Telescope  (hskymon)
#                         Document file
#
#
#                                  ver 4.5.7    2023/08/25
#                               Copyright (C) 2003-23 Akito Tajitsu
#                                        akito.tajitsu_at_nao.ac.jp
#      Subaru Telescope, National Astronomical Observatory of Japan
#########################################################################


*** Introduction
This program (hskymon) is a GTK+2/3 based telescope monitoring 
application for SUBARU Telescope, National Astronomical Observatory
of Japan.
It can be useful for actual observation and also for obs preparation 
as a telescope simulator.
Basically, hskymon is optimized for Subaru Telescope. However,
it can be adopted to other telescopes, changing positional parameters.

For target lists to display on the program, you can input OPE
files for SOSs or CSV text lists.

The latest version (source code and Win/Mac binary packages) can be 
found  in the official page of NAOJ,
  https://www.naoj.org/Observing/tools/hskymon/
or in in GitHub,
  https://github.com/chimari/hskymon/
.
If you want to make a clone of the latest source code via GitHub, use
  git clone https://github.com/chimari/hskymon.git
in your terminal.

*** Environment
hskymon requires UNIX operating system with X window system,
Microsoft Windows (7 or later), or mac OS (Mavericks or later).

To compile this program from its source code, you need to install
Gtk+ development tools (for Windows, the maintainer is using msys2).
Either Gtk+2 (>2.24; default) or Gtk+3 (>3.22) is required.
libxml2, openssl, and json-c are also required to build the program.

In order to get telescope status, hskymon requires xmlrpc-c library.
But, Windows/Mac version does not support this function.
You need to install some libraries and developer's environment for them
to make this program.
(gtk+2-dev, xmlrpc-c3-dev, libcurl4-openssl-dev ... etc.)

If you are using an internet security software (ESET etc.), you may
have problems on HTTP/HTTPS accesses on hskymon (stacks, slowness...).
In such cases, please try to add
  C:\Program Files\Subaru Telescope\hskymon\hskymon.exe  (Win)
  /Applications/hskymon.app/Contents/MacOS/hskymon-bin   (mac)
to the exclusion list in your security software.


*** Build from the source code
  - Extract the source archive and enter to the extracted directory.

  - (only when you cloned the source tree by git)
    % touch configure configure.ac aclocal.m4 Makefile.am Makefile.in

  - % ./configure
      [option]
        --with-gtk3   : use Gtk+3 instead of Gtk+2
        --with-xmlrpc : make w/xmlrpc to get telescope status in Gen2
        --with-win32  : make for Windows (32bit/64bit)
        --with-gtkmac : make w/gtk-mac-integration for mac OS
        --with-maintain : designate deprecated functions (for maintainer)

    If you failed in configure (possiblly aclocal error),
    Please try
           % /autogen.sh
    before your configure session.

  - % make
    Then, an executable file "hskymon" will be created.

  - # make install  
    (or you can copy "hskymon" file to an appropriate directory.)


*** Command line option
     -h, --help                    : Print help message
     -i, --input [input-file]      : Set the input CSV list file
     -a, --with-allsky             : Switch on All Sky Camera
     -nt, --without-telstat        : Switch off to read Telescope Status
     -s, --server [server-address] : Override Telstat Server
     -l, --log [log-file]          : Output log file


*** XMLRPC
If you compiled hskymon with "xmlrpc" option, hskymon can get the current
telescope status from Subaru Gen2 server (effective only in the Subaru
summit network.)
In this case, you should set the address of Gen2 status server
 [1] by a commandline option "-s" (or "--server")
       % hskymon -s status.server.address.foo.bar
or
 [2] by an environment variable  "GEN2_RO_SERVER"
. The environment variable [2] yields to the command line option [1].
If either [1] or [2] is found in the start up, hskymon aborts to communicate
with the status server.


*** Input files
[1]OPE file
OPE files for SOSs can be available for objects inputs.
hskymon reads the parameter list section in OPE files likely,

   <PARAMETER_LIST>

   TGT_BD44493=OBJECT="BD+44 493" RA=022649.60 DEC=+445746.80 EQUINOX=2000.00
   TGT_HD222304=OBJECT="HD222304" RA=033908.30 DEC=+502818.20 EQUINOX=2000.00
   TGT_HD224544=OBJECT="HD224544" RA=235849.20 DEC=+322254.10 EQUINOX=2000.00
   TGT_HD225132=OBJECT="HD225132" RA=000344.40 DEC=-172009.50 EQUINOX=2000.00
           ....................................

All characters in the objectname will be capitalized.

.prm files in which standard stars are defined are also loaded
automatically.
You should write command to load *.prm files likely

*LOAD "hogehoge.prm"

in the <PARAMETER> field of OPE files.
# double quotation is required for the file name.
Current searching paths for *.prm files are
  1.  same directory with the loaded *.ope
  2.  subdirectory "COMMON/"
  3.  same level directory "../COMMON/"
  4.  "~/Procedure/"
  5.  "~/Procedure/<INST>/"
  6.  "~/Procedure/<INST>/COMMON/"
  7.  "~/Procedure/COMMON/"


As default, hskymon displays all objects defined in the loaded OPE file.
If you want to hide unused objects (in "GetObject*", "GetStandard*" or 
"SetupField*" commands in <COMMAND> field of the OPE file),
you can hide them with "Hide Objects unused in OPE file" button
(the 2nd button in ASC/Telstat menu). 

For .prm files, the objects are loaded only in the case that it is used
in commands ("GetObject*", "GetStandard*" or "SetupField*") in the OPE
file.


[2]CSV Text file
The text files written in the following CSV format are also available for
objects inputs.

	HD94028     ,105128.1 ,+201639.0 ,2000,  <comments>
	BD+36 2165  ,111248.0 ,+354343.9 ,2000,  Mv=8.4  Fe/H=-2
	HD97916     ,111554.2 ,+020512.1 ,2000,  Mv=10.2 Fe/H=-2
	BD+51 1696  ,114635.2 ,+505254.7 ,2000   
	BD-13 3442  ,114650.7 ,-140643.5 ,2000,
           ....................................


[3] Non-Sidereal Tracking File (TSC format)
Non-Sidereal tracking files for TSC can also be avairable.
Please put TSC files in an appropriate directory (maybe in the same 
directory where your OPE files locate) and load them from the menu.
Files must follow the format described in
  https://www.naoj.org/Observing/Telescope/Tracking/NonSidereal/
. You should use "Geocentric" coordinate in TSC files.
They would be automatically converted into topocentric in the program.
When hskymon's time and date are out of the range of the tracking 
calculation, the object will be plotted with an "x" mark in the monitor.
You can check the orbit of the non-sidereal target in the Finsing Chart.


[4] Non-Sidereal Tracking File (JPL HORIZONS format)
hskymon can also load NASA JPL HIRIZONS output files.
  https://ssd.jpl.nasa.gov/horizons.cgi
Please note that you should set 
   "Epehmeris Type" = OBSERVER
   "Observer Location" = Geocentric
   "Table Settings" = 1. Astrometric RA & Dec, 20. Observer range
for your input.
Either calendar date or JD is acceptable for date format.
From the main menu, HORIZONS files can be converted into the TSC format.


*** Copyright
   The code in this distribution is Copyright 2003-2018 by Akito Tajitsu.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; either version 3, or (at your option)
   any later version.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program; if not, write to the Free Software
   Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA

   In addition, as a special exception, A.Tajitsu gives permission to link 
   this code of this program with the OpenSSL library (or with modified
   versions of OpenSSL that use the same license as OpenSSL), and distribute
   linked combinations including the two. You must obey the GNU General 
   Public License in all respects for all of the code used other than OpenSSL.
   If you modify this file, you may extend this exception to your version of 
   the file, but you are not obligated to do so. If you do not wish to do so,
   delete this exception statement from your version.