\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}


