add J2000 coordinates calculation

doc/doc.tex

@@ -0,0 +1,309 @@
+\documentclass[a4paper,12pt]{extarticle}
+\usepackage[koi8-r]{inputenc}
+\usepackage[english,russian]{babel}
+\usepackage{hyperref}
+\usepackage{ifpdf}              % проверка pdflatex/latex
+\ifpdf
+        \usepackage[pdftex]{graphicx}
+        \usepackage{cmap}
+        \ExecuteOptions{pdftex}
+\else
+        \usepackage[dvips]{graphicx}
+\fi
+\textwidth=17.5cm
+\oddsidemargin=-.3cm
+\evensidemargin=-1.2cm
+\topmargin=-1cm
+\textheight=24cm
+\begin{document}
+\title{Описание параметров командной строки интерфейса управления ПЗС-камерами Apogee}
+\author{Емельянов Э.В.}
+\maketitle
+
+Утилита \verb'apogee_control' предназначена для работы с рядом ПЗС-камер фирмы Apogee Imaging
+Systems (протестирована на камерах Apogee Alta и Apogee Aspen). Позволяет управлять параметрами
+ПЗС-камер, получать изображение с камер, отображать его на экране и\slash или сохранять в FITS-файл.
+При работе на компьютере в сети САО РАН с запущенной системой \verb'bta_control_net' утилита также
+добавляет в FITS-заголовок файла сведения о телескопе.
+
+Помимо работы с ПЗС-камерами утилита может также управлять турелями фирмы Apogee.
+
+\section{Сборка и установка}
+Утилита использует библиотеку
+\verb'libapogee'\footnote{\url{http://www.randomfactory.com/downloads/}}, а т.к. сама библиотека
+написана на C++, дополнительно используется промежуточный интерфейс к С. Библиотека и сишный
+интерфейс находятся в одном репозитории с утилитой. Скачать их можно командой
+\begin{verbatim}
+git clone https://github.com/eddyem/apogee_control.git
+\end{verbatim}
+В результате весь репозиторий будет сохранен в директорию \verb'apogee_control'. Внутри нее в
+директории \verb'libapogee' находится несколько версий библиотек. Для работы с камерами Aspen
+необходимо установить наиболее свежую.
+\subsection{Установка libapogee}
+Распаковываем библиотеку и входим в корневую директорию архива:
+\begin{verbatim}
+tar -zxf libapogee-3.0.3179.tgz
+cd libapogee-3.0.3179/
+\end{verbatim}
+Затем конфигурируем, собираем и устанавливаем:
+\begin{verbatim}
+./configure && make && su -c "make install"
+\end{verbatim}
+В случае нехватки каких-либо библиотек на стадии \verb'./configure' появятся сообщения об ошибке,
+недостающее необходимо установить.
+
+\subsection{Установка С-интерфейса к библиотеке}
+Сишный интерфейс к \verb'libapogee' находится в директории \verb'apogee_C_wrapper' репозитория.
+Система сборки интерфейса и самой утилиты основана на \verb'cmake'. Для сборки интерфейса выполняем:
+\begin{verbatim}
+mkdir mk && cd mk
+cmake .. && make && su -c "make install"
+\end{verbatim}
+Для отображения отладочных сообщений на стадии \verb'cmake' можно указать
+\begin{verbatim}
+cmake .. -DEBUG=1
+\end{verbatim}
+
+\subsection{Установка утилиты}
+Код самой утилиты находится в корневой директории репозитория. Для установки выполняем те же
+действия, что и в случае С-интерфейса:
+\begin{verbatim}
+mkdir mk && cd mk
+cmake .. && make && su -c "make install"
+\end{verbatim}
+Для \verb'cmake' в данном случае доступны следующие ключи:
+\begin{description}
+\item[-DNOBTA=1] отключить вывод параметров телескопа БТА в заголовок FITS-файла, даже если на
+компьютере с утилитой запущен демон \verb'bta_control_net';
+\item[-DUSERAW=1] сохранять изображения в <<сырой>> бинарный формат помимо FITS;
+\item[-DUSEPNG=1] сохранять изображения в формат PNG помимо FITS;
+\item[-DEBUG=1] отображать отладочные сообщения;
+\item[-DTELLAT=<lat>] установить широту телескопа для отображения в заголовке FITS-файла;
+\item[-DTELLONG=<long>] установить долготу телескопа;
+\item[-DTELALT=<alt>] задать высоту расположения телескопа относительно уровня моря.
+\end{description}
+При записи в заголовок FITS-файла данных АСУ БТА утилита также вычисляет атмосферные параметры по
+Риду Д.\,Мейеру (Reed D.\,Meyer): воздушную массу, долю водяных паров, плотность столба атмосферы,
+плотность столба водяного пара. Кроме того, существует возможность сохранять текущие
+метеорологические параметры и некоторые параметры АСУ в \verb'HISTORY' FITS-файла.
+
+\section{Работа с утилитой}
+Сообщения, выдаваемые утилитой, локализованы при помощи \verb'gettext' (однако, по мере разработки
+возможны некоторые пробелы в локализации). Общая справка по параметрам командной строки выводится
+при запуске утилиты без параметров.
+
+На дату написания данного руководства полный список параметров следующий:
+\begin{verbatim}
+Использование:	apogee_control [опции] [префикс выходных файлов]
+	Опции:
+	-A,	--author=author		автор программы
+	-c,	--cooler-off		отключить холодильник
+	-d,	--dark			не открывать затвор при экспозиции ("темновые")
+	-D,	--display-image		Отобразить на экране полученное изображение
+	-E,	--ether-subnet		Subnet fot ethernet camera discovery
+	-f,	--no-flash		не засвечивать матрицу перед экспозицией
+	-F,	--fan-speed=F		Установить скорость вентиляторов в F (0..3)
+	-g,	--wheel-get		получить сведения о турели
+	-G,	--wheel-go=N		переместить турель в N-ю позицию
+	-H,	--time-interval=T	интервал времени между последовательными записями в лог
+	                       и HISTORY (в секундах)
+	-h,	--hbin=N		биннинг N пикселей по горизонтали
+	-I,	--image-type=type	тип изображения
+	-i,	--instrument=instr	название прибора
+	-L,	--log-only		не сохранять изображения, лишь вести запись статистки
+	-l,	--tlog			вести запись рабочих температур в файл temp_log
+	-M,	--msg-id		open camera by its MSG-ID
+	-N,	--ncam=N		работать с N-й камерой
+	-n,	--nframes=N		N кадров в серии
+	-O,	--object=obj		название объекта
+	-o,	--observer=obs		имена наблюдателей
+	-P,	--prog-id=prname	название программы наблюдений
+	-p,	--pause-len=ptime	выдержать ptime секунд между экспозициями
+	-r,	--speed-set=N		установить скорость считывания в N
+	-R,	--reset			Полный сброс
+	-S,	--sleep			перейти в спящий режим
+	-s,	--only-stat		не сохранять изображение, а только отобразить статистику
+	-T,	--only-temp		только задать/получить температуру
+	-t,	--set-temp=degr		задать рабочую температуру degr градусов
+	-v,	--vbin=N		биннинг N пикселей по вертикали
+	-w,	--wheel-num=N		установить номер турели в N
+	-W,	--wakeup		возобновить питание
+	-x,	--exp=exptime		время экспозиции exptime мс
+	-X,	--xclip=X0[,X1]		выбрать диапазон для считывания [X0:X1]
+	-Y,	--xclip=Y0[,Y1]		выбрать диапазон для считывания [Y0:Y1]
+		--flipX			отразить изображение вертикально (относительно оси X)
+		--flipY			отразить изображение горизонтально (относительно оси Y)
+		--noclean		не очищать матрицу после считывания
+		--pre-exp		выполнить предварительную нулевую экспозицию для очистки матрицы
+		--shutter-open		открыть затвор
+		--shutter-close		заткрыть затвор
+		--test-headers		не открывать устройство, лишь отобразить шапку FITS
+		--twelve-bit		работать в 12-битном режиме
+\end{verbatim}
+Некоторые (наиболее редко используемые) параметры имеют только <<длинный>> формат параметра.
+\subsection{Управление параметрами камеры и кадра}
+\begin{description}
+\item[-c, -{}-cooler-off] отключить подачу напряжения на элемент Пельтье (для выхода ПЗС на
+комнатную	температуру);
+\item[-d, -{}-dark] снимать <<темновые>> кадры --- не открывать затвор при экспозиции;
+\item[-E, -{}-ether-subnet=subn] задать подсеть (в виде маски адресов или конкретного IP-адреса)
+	при работе с сетевой версией Apogee Aspen, например, \verb'-E 192.168.0.255' для поиска
+	камеры в сети \verb'192.168.0.0/24';
+\item[-M, -{}-msg-id=ID] попытаться подключиться к камере с конкретным идентификатором, данный
+идентификатор выдается утилитой при подключении к камере, пример:
+\begin{verbatim}
+apogee_control -M interface=ethernet,deviceType=camera,
+address=192.168.99.121,port=80,mac=000951ffffff81ffffffed22,
+interfaceStatus=Available,id=0x1a3,firmwareRev=0x132,model=Aspen-16M
+\end{verbatim}
+данный параметр позволяет ускорить процесс работы с сетевыми камерами;
+\item[-f, -{}-no-flash] не выполнять предварительную засветку ПЗС встроенным ИК-светодиодом
+	при экспозиции (работает не для всех камер);
+\item[-F, -{}-fan-speed=F] принудительно установить скорость вращения вентиляторов, величина
+	скорости изменяется от 0~(выключены) до 3~(наибольшая скорость);
+\item[-h, -{}-hbin=N] горизонтальный биннинг (предельное значение N зависит от типа ПЗС);
+\item[-v, -{}-vbin=N] вертикальный биннинг (предельное значение N зависит от типа ПЗС);
+\item[-N, -{}-ncam=N] если обнаружено несколько ПЗС-камер, работать с N-й;
+\item[-n, -{}-nframes=N] провести серию снимков из N~кадров;
+\item[-p, -{}-pause-len=ptime] выдержать \verb'ptime' секунд паузы между кадрами при работе с
+	серией кадров;
+\item[-r, -{}-speed-set=N] устаревший параметр для задания скорости считывания (не работает
+	с большинством современных камер);
+\item[-{}-twelve-bit] двенадцатибитный режим работы (высокая скорость считывания);
+\item[-R, -{}-reset] полный сброс параметров камеры (работает не на всех камерах);
+\item[-S, -{}-sleep] перевод камеры в спящий режим (работает не на всех камерах);
+\item[-T, -{}-only-temp] только задать\slash отобразить температуру узлов камеры;
+\item[-t, -{}-set-temp=degr] установить температуру чипа ПЗС в \verb'degr' градусов Цельсия;
+\item[-W, -{}-wakeup] выйти из спящего режима (работает не на всех камерах);
+\item[-x, -{}-exp=exptime] установить время экспозиции каждого кадра в \verb'exptime' миллисекунд;
+\item[-X, -{}-xclip=X0$\lbrack$,X1$\rbrack$] выбрать поддиапазон для считывания по оси~X;
+\item[-Y, -{}-xclip=Y0$\lbrack$,Y1$\rbrack$] выбрать поддиапазон для считывания по оси~Y;
+\item[-{}-flipX] отразить изображение вертикально (относительно оси X);
+\item[-{}-flipY] отразить изображение горизонтально (относительно оси Y);
+\item[-{}-noclean] не очищать матрицу после считывания (т.е. не удалять остаточный сигнал, работает
+	не на всех камерах);
+\item[-{}-pre-exp] выполнить предварительную нулевую экспозицию (бывает необходимо для того,
+	чтобы параметры камеры наверняка успели правильно выставиться перед выполнением основных
+	экспозиций; без этого параметра возможны излишние шумы или даже повреждение кадра вследствие
+	начала считывания не с нулевой позиции);
+\item[-{}-shutter-open] открыть затвор;
+\item[-{}-shutter-close] заткрыть затвор.
+\end{description}
+\subsection{Управление параметрами заголовка FITS-Файлов}
+Часть параметров заголовка формируемых FITS-файлов задается аргументами командной строки:
+\begin{description}
+\item[-A, -{}-author=author] автор программы (\verb'AUTHOR');
+\item[-I, -{}-image-type=type] тип изображения (\verb'IMAGETYP');
+\item[-i, -{}-instrument=instr] название прибора (\verb'INSTRUME');
+\item[-O, -{}-object=obj] название объекта (\verb'OBJECT');
+\item[-o, -{}-observer=obs] имена наблюдателей (\verb'OBSERVER');
+\item[-P, -{}-prog-id=prname] название программы наблюдений (\verb'PROG-ID');
+\item[-{}-test-headers] не снимать ни единого кадра, а только отобразить заголовок,
+	который писался бы в формируемый FITS-файл (некоторые параметры будут неверными ввиду
+	отсутствия изображения).
+\end{description}
+Если не указывать ключ \verb'-I', при съемке обычных кадров в поле \verb'IMAGETYP' заголовка
+FITS-файла будет указано: <<object>>; если же задать ключ \verb'-d' для съемки темновых, тип будет
+установлен в <<dark>>; при установки нулевой экспозиции (\verb'-x 0') в качестве типа изображения
+будет указано <<bias>>.
+
+Содержимое многих ключей заголовка FITS-файла не соответствует стандарту и будет исправлено при
+дальнейших модификациях утилиты.
+
+\subsection{Работа с турелями Apogee}
+\begin{description}
+\item[-g, -{}-wheel-get] получить сведения о турели;
+\item[-G, -{}-wheel-go=N] переместить турель в N-ю позицию;
+\item[-w, -{}-wheel-num=N] если к компьютеру подключено несколько турелей, выбрать N-ю для
+	дальнейшей работы.
+\end{description}
+
+\subsection{Статистика, логгирование и сохранение\slash отображение}
+После съемки очередного кадра в командной строке выводится основная статистическая информация
+по изображению. Изображение в дальнейшем может быть уничтожено, сохранено и\slash или отображено
+на экране.
+
+Если утилита \verb'apogee_control' вызывается без указания префикса выходных файлов, изображения
+только отображаются на экране (если не указано противного). Помимо этого, утилита способна
+сохранять статистические параметры отснятых кадров в лог-файл (скажем, для получения простых
+температурных зависимостей).
+
+\begin{description}
+\item[-D, -{}-display-image] данный параметр позволяет отображать отснятые изображения даже если
+	указан префикс файла для сохранения; чтобы закрыть окно с последним изображением серии,
+	необходимо либо нажать в окне клавишу ESC, либо в консоли сочетание Ctrl+C. Окно с изображением
+	можно масштабировать, также при помощи колеса мыши с зажатой клавишей Ctrl можно масштабировать
+	само изображение внутри окна, а средней кнопкой мыши перемещать его. По нажатию правой кнопки
+	мыши появляется меню, позволяющее восстановить исходный масштаб изображения или закрыть окно;
+\item[-H, -{}-time-interval=T] интервал времени между последовательными записями в лог
+	и HISTORY (в секундах);
+\item[-L, -{}-log-only] не сохранять изображения, лишь вести запись статистки в лог;
+\item[-l, -{}-tlog] отдельно вести запись рабочих температур в файл \verb'temp_log';
+\item[-s, -{}-only-stat] не сохранять изображение, а только отобразить статистику.
+\end{description}
+
+
+\section{Заголовки FITS-файлов}
+Набор генерируемых утилитой заголовков FITS-файлов зависит от того, скомпилирована ли утилита с
+поддержкой АСУ БТА и запущен ли на компьютере демон АСУ. Минимальный общий набор заголовков
+следующий:
+\begin{description}
+\item[FILE] название оригинального файла;
+\item[INSTRUME] название прибора (по умолчанию <<direct imaging>>);
+\item[PXSIZE] размер пикселя в мкм вида <<H x V>>;
+\item[XPIXELSZ, YPIXELSZ] горизонтальный и вертикальный размер пикселя в мкм (число с плавающей
+	точкой);
+\item[VIEW\_FIELD] поле зрения камеры в пикселях;
+\item[CRVAL1, CRVAL2] (-1);
+\item[IMAGETYP] тип изображения;
+\item[DATAMAX, DATAMIN] наибольшее и наименьшее значение в рабочем диапазоне (для 16 бит этого
+	65535 и 0 соответственно);
+\item[STATMAX, STATMIN] статистические максимум и минимум по изображению;
+\item[STATAVR, STATSTD] среднее и среднеквадратическое значения по изображению;
+\item[TEMP0, TEMP1] температура чипа ПЗС на момент начала и окончания экспозиции соответственно
+	($^\circ C$);
+\item[TEMPBODY] температура горячего спая Пельтье на время окончания экспозиции ($^\circ C$);
+\item[CAMTEMP] температура чипа в Кельвинах на окончание экспозиции;
+\item[EXPTIME] время экспозиции в секундах;
+\item[DATE] дата и время запуска утилиты, UTC;
+\item[DATE-OBS] местные дата и время записи файла;
+\item[XBIN, YBIN] биннинг.
+\end{description}
+
+При поддержке АСУ БТА набор заголовков дополняется следующими:
+\begin{description}
+\item[TELESCOP] название телескопа (<<BTA 6m telescope>>);
+\item[ORIGIN] название организации (<<SAO RAS>>);
+\item[OBSERVAT] название обсерватории (<<Special Astrophysical Observatory, Russia>>)
+\item[ALT\_OBS] высота над уровнем моря (2070);
+\item[LONG\_OBS] долгота в градусах (41.4414);
+\item[LAT\_OBS] широта в градусах (43.6535);
+\item[ST] звездное время в секундах (в комментарии также указано в строковом формате);
+\item[UT] UTC в секундах (в комментарии также указано в строковом формате);
+\item[JD] юлианская дата (пока что -- в неправильном формате);
+\item[FOCUS] фокус: <<Prime>> или <<Nesmith>>;
+\item[VAL\_F] значение отсчета фокуса в миллиметрах;
+\item[EQUINOX] эпоха значений RA/DEC (обычно -- дата получения изображения в годах);
+\item[RA, DEC] полярные координаты объекта на эпоху EQUINOX;
+\item[S\_RA, S\_DEC] введенные пользователем координаты;
+\item[T\_RA, T\_DEC] координаты телескопа;
+\item[A, Z] горизонтальные координаты видимого места объекта;
+\item[ROTANGLE] параллактический угол;
+\item[VAL\_A, VAL\_Z] горизонтальные координаты телескопа;
+\item[VAL\_P] значение отсчетов с поворотного стола P2 (в градусах);
+\item[VAL\_D] азимут купола;
+\item[OUTTEMP] внешняя температура;
+\item[DOMETEMP] температура в подкупольном;
+\item[MIRRTEMP] температура зеркала;
+\item[PRESSURE] атмосферное давление, мм.рт.ст.;
+\item[WIND] скорость ветра;
+\item[HUM] влажность;
+\item[AIRMASS] воздушная масса;
+\item[WVAM] воздушная масса водяных паров;
+\item[ATMDENS] давление атмосферного столба;
+\item[WVDENS] давление столба водяных паров.
+\end{description}
+
+\end{document}
+
+