docs/kdeedu/kstars/scriptbuilder.docbook

   1 <sect1 id="tool-scriptbuilder">
   2 <title
   3 >Редактор сценариев</title>
   4 <indexterm
   5 ><primary
   6 >Инструменты</primary>
   7 <secondary
   8 >Редактор сценариев</secondary>
   9 </indexterm>
  10
  11 <para
  12 >Приложения KDE могут управляться из других приложений, из командной строки, или с помощью Коммуникационного Протокола Рабочего Стола (Desktop COmmunication Protocol -- <abbrev
  13 >DCOP</abbrev
  14 >). &kstars; предоставляет набор расширений, позволяющих лучше контролировать изображение с помощью сценариев. Эти возможности позволяют, например, создавать демонстрации иллюстрирующие основные концепции астрономии. </para>
  15 <para
  16 >Написание DCOP скриптов все-таки является программированием, что может отпугнуть тех, у кого нет опыта программирования. Редактор сценариев предоставляет графический интерфейс (<abbrev
  17 >GUI</abbrev
  18 >) для конструирования DCOP сценариев &kstars;, что сильно упрощает написание сценариев. </para>
  19
  20 <sect2 id="sb-intro">
  21 <title
  22 >Введение в редактор сценариев</title>
  23
  24 <para
  25 >Перед тем как подробно описывать как пользоваться редактором сценариев, прочтите небольшое вступление обо всех компонентах графического интерфейса. Для более подробной информации воспользуйтесь функцией "справка". </para>
  26
  27 <screenshot>
  28 <screeninfo
  29 >Редактор сценариев </screeninfo>
  30 <mediaobject>
  31   <imageobject>
  32     <imagedata fileref="scriptbuilder.png" format="PNG"/>
  33   </imageobject>
  34   <textobject>
  35     <phrase
  36 >Редактор сценариев</phrase>
  37   </textobject>
  38 </mediaobject>
  39 </screenshot>
  40
  41 <para
  42 >На рисунке ниже представлен редактор сценариев. Панель слева -- <firstterm
  43 >Текущий скрипт</firstterm
  44 >;там показаны команды, которые вы уже включили в сценарий. Панель справа -- <firstterm
  45 >Браузер функции</firstterm
  46 >; там показан список всех доступных функций. Ниже браузера функций расположена небольшая панель, в которой содержится краткое описание функции выбранной в браузере. Панель ниже текущего скрипта -- <firstterm
  47 >Аргументы функций</firstterm
  48 >; где вы можете изменить аргументы функции выделенной в текущем скрипте. </para
  49 ><para
  50 >Вверху расположен ряд кнопок, которые оперируют со сценарием как с целым: это (слева на право) <guibutton
  51 >Создать скрипт</guibutton
  52 >, <guibutton
  53 >Открыть скрипт</guibutton
  54 >, <guibutton
  55 >Сохранить скрипт</guibutton
  56 >, <guibutton
  57 >Сохранить скрипт как...</guibutton
  58 >, и <guibutton
  59 >Тестировать скрипт</guibutton
  60 >. Значение этих кнопок очевидны, за исключением, может быть, последней. Нажав на кнопку <guibutton
  61 >Тестировать скрипт</guibutton
  62 > вы запустите его в главном окне &kstars;. Отодвиньте окно Редактора сценариев в сторону, перед тем как нажимать эту кнопку, чтобы увидеть результат выполнения сценария. </para
  63 ><para
  64 >В центре окна расположены кнопки, которые работают с отдельными функциями сценария. Это (сверху вниз): <guibutton
  65 >Добавить функцию</guibutton
  66 >, <guibutton
  67 >Удалить функцию</guibutton
  68 >, <guibutton
  69 >Копировать функцию</guibutton
  70 >, <guibutton
  71 >Выше</guibutton
  72 >, и <guibutton
  73 >Ниже</guibutton
  74 >. <guibutton
  75 >Добавить функцию</guibutton
  76 > -- добавляет выделенную в браузере функцию в текущий сценарий (вы также можете добавить функцию дважды щёлкнув на её названии мышью). Остальные кнопки оперируют с функциями выделенными в текущем сценарии, т.е. позволяют удалять их, копировать, изменять их положение. </para>
  77 </sect2>
  78
  79 <sect2 id="sb-using">
  80 <title
  81 >Использование Редактора сценариев</title>
  82 <para
  83 >В качестве иллюстрации использования редактора сценариев, мы приведём небольшой пример, где сделаем скрипт, который покажет след Луны, пока часы симуляции идут в ускоренном режиме. </para
  84 ><para
  85 >Прежде чем нарисовать след Луны, нужно привязать к ней экран. Для этого используем функцию <firstterm
  86 >lookToward</firstterm
  87 >. выделите эту функцию в списке справа, и обратите внимание, что описание этой функции появилось в панели ниже. Нажмите кнопку <guibutton
  88 >Добавить функцию</guibutton
  89 > , чтобы добавить функцию к текущему сценарию. Теперь в панели Аргументы функцийпоявился выпадающий список <quote
  90 >направление</quote
  91 >, где вы можете выбрать направление, на которое будет привязан экран. В выпадающем списке содержаться только направления света, но нет объектов, таких как, например, Луна. Вы можете ввести имя объекта (<quote
  92 >Луна</quote
  93 >) в выпадающий список вручную, или воспользоваться окном <guilabel
  94 >Поиск объекта</guilabel
  95 > нажав кнопку <guibutton
  96 >Объект</guibutton
  97 >. Заметьте, если вы привязали экран к объекту, то автоматически начинается слежение за объектом, таким образом нет необходимости добавлять функцию <firstterm
  98 >setTracking</firstterm
  99 > перед lookToward. </para
 100 ><para
 101 >Итак, теперь экран центрирован на Луну, следующим шагом мы хотим ускорить время. Для этого используйте функцию <firstterm
 102 >setClockScale</firstterm
 103 >. Добавьте её в сценарий, одним из описанных выше методов. После этого на панели Аргументы функций появиться окошечко счётчика, с помощью которого вы можете установить требуемую скорость течения времени симуляции. Установите скорость на 3 часа. </para
 104 ><para
 105 >Итак, мы привязали экран к Луне и ускорили время. теперь мы просто хотим приостановить исполнение сценария. Добавьте функцию <firstterm
 106 >waitFor</firstterm
 107 > и установите паузу на 20с., используя панель Аргументов функций. </para
 108 ><para
 109 >В завершение, установим скорость течения времени 1с. Добавьте ещё один экземпляр setClockScale, и установите значение аргумента - 1с. </para
 110 ><para
 111 >Однако, в приведённом сценарии есть один недостаток. Мы должны сперва убедиться, что для отрисовки используются Экваториальные координаты, прежде чем начнём следить за Луной. Если используются Горизонтальные координаты, то на экране вы увидите очень быстрое вращение небесной сферы. Чтобы этого не произошло, установите параметр вида <firstterm
 112 >UseAltAz</firstterm
 113 > в <quote
 114 >false</quote
 115 >. Чтобы изменить какой-либо параметр вида, используйте функцию <firstterm
 116 >changeViewOption</firstterm
 117 >. Добавьте эту функцию к сценарию, и обратите внимание на панель аргументов функций. Здесь есть выпадающий список, содержащий все параметры вида. Так как мы точно знаем название опции, то мы можем просто выбрать её из списка. Если вы не знаете название необходимой опции, нажмите на кнопку <guibutton
 118 >Просмотреть дерево</guibutton
 119 >, чтобы открыть окно, которое показывает опции по разделам. Кроме того, рядом с каждой опцией содержится краткое описание, за что она отвечает, и тип аргументов и их предельные значения. Так опцию UseAltAz мы найдём в разделе <guilabel
 120 >Настройка звёздного неба</guilabel
 121 >. Выберите опцию и нажмите кнопку <guibutton
 122 >OK</guibutton
 123 >, после этого опция будет выбрана в выпадающем списке в панели аргументов функций. Наконец в поле Значение, наберите <quote
 124 >false</quote
 125 > или <quote
 126 >0</quote
 127 >. </para
 128 ><para
 129 >Ещё один шаг: изменение опции UseAltAz в конце сценария не принесёт желаемого результат; мы должны изменить эту опцию в начале сценария. Для этого убедитесь что выделена нужная функция в панели текущий скрипт, и нажимайте кнопку <guibutton
 130 >Выше</guibutton
 131 >, до тех пор, пока функция не окажется вверху. </para
 132 ><para
 133 >Теперь, когда сценарий написан, нужно сохранить его на диск. Для этого нажмите кнопку <guibutton
 134 >Сохранить скрипт</guibutton
 135 >. Сперва откроется окно, где вам предложат ввести название сценария и ваше имя, как имя автора. Для примера, в качестве названия сценария введите <quote
 136 >Слежение за луной</quote
 137 >, и своё имя в поле автор, и нажмите <guibutton
 138 >OK</guibutton
 139 >. После этого откроется стандартный диалог &kde; Сохранить файл. Введите название файла, и нажмите <guibutton
 140 >OK</guibutton
 141 >, чтобы сохранить сценарий. Заметьте, что если имя файла НЕ оканчивается <quote
 142 >.kstars</quote
 143 >, то этот суффикс будет добавлен автоматически. Если вы чувствуете себя опытным пользователем, вы можете отредактировать сценарий вручную, с помощью любого текстового редактора. </para
 144 ><para
 145 >Готовый сценарий, можно запустить множеством способов. Из командной строки можно запустить только если &kstars; уже запущен. Также вы можете запустить сценарий из &kstars; с помощью пункта <guimenuitem
 146 >Запустить сценарий</guimenuitem
 147 >, меню <guimenuitem
 148 >Файл</guimenuitem
 149 >. </para>
 150 </sect2>
 151
 152 <sect2 id="sb-indi">
 153   <title
 154 >Управление устройствами с помощью INDI</title>
 155   <para
 156 >Автоматизация управления доступна для всех устройств совместимых с протоколом <link linkend="what-is-indi"
 157 >INDI</link
 158 >. Вы можете координировать работу любого количества устройств с помощью <link linkend="sb-intro"
 159 >Генератора сценариев</link
 160 > &kstars;. Управление можно улучшить, используя интерфейс INDI DCOP, который предоставляет различные функции для решения ваших задач. Функции INDI DCOP можно разбить на четыре класса. Далее следует обзор функций и их аргументов, поддерживаемых &kstars; Перед использованием, мы рекомендуем сперва познакомиться с <link linkend="indi-concepts"
 161 >Концепцией INDI</link
 162 >.</para>
 163   <orderedlist>
 164     <listitem
 165 ><para
 166 >Основные функции устройств (Generic Device Functions): например функции включения/выключения устройств и т.п. ...</para>
 167       <itemizedlist>
 168         <listitem
 169 ><para
 170 ><function
 171 >startINDI (QString deviceName, bool useLocal)</function
 172 > : Устанавливает INDI сервис, как локальный для данного компьютера или как сервер.</para
 173 ></listitem>
 174         <listitem
 175 ><para
 176 ><function
 177 >shutdownINDI (QString deviceName)</function
 178 > : Останавливает INDI сервис. </para
 179 ></listitem>
 180         <listitem
 181 ><para
 182 ><function
 183 >switchINDI(QString deviceName, bool turnOn)</function
 184 > : Подключает, или отключает устройство (работающее по протоколу) INDI.</para
 185 ></listitem>
 186         <listitem
 187 ><para
 188 ><function
 189 >setINDIPort(QString deviceName, QString port)</function
 190 > : Устанавливает порт подключения устройства.</para
 191 ></listitem>
 192         <listitem
 193 ><para
 194 ><function
 195 >setINDIAction(QString deviceName, QString action)</function
 196 > : Выполняет действие INDI. Действие может быть - <emphasis
 197 >element</emphasis
 198 > или <emphasis
 199 >switch property</emphasis
 200 ></para
 201 ></listitem>
 202         <listitem
 203 ><para
 204 ><function
 205 >waitForINDIAction(QString deviceName, QString action)</function
 206 > : Приостановить выполнение сценария, пока <emphasis
 207 >свойство</emphasis
 208 > действия не вернёт успешный статус завершения.</para
 209 ></listitem>
 210       </itemizedlist>
 211     </listitem>
 212     <listitem
 213 ><para
 214 >Функции телескопов (Telescope Functions): функции управления движением телескопа и его состоянием.</para>
 215       <itemizedlist>
 216         <listitem
 217 ><para
 218 ><function
 219 >setINDIScopeAction(QString deviceName, QString action)</function
 220 > : Установить режим, или действие телескопа. возможные значения - SLEW, TRACK, SYNC, PARK, и ABORT.</para
 221 ></listitem>
 222         <listitem
 223 ><para
 224 ><function
 225 >setINDITargetCoord(QString deviceName, double RA, double DEC)</function
 226 > : установить координаты "цели" телескопа.</para
 227 ></listitem>
 228         <listitem
 229 ><para
 230 ><function
 231 >setINDITargetName(QString deviceName, QString objectName)</function
 232 > : Установить координаты "цели" по имени <emphasis
 233 >objectName</emphasis
 234 >. &kstars; ищет имя объекта в своей базе данных, и автоматически задаёт значения склонения и восхождения, если они есть в базе данных..</para
 235 ></listitem>
 236         <listitem
 237 ><para
 238 ><function
 239 >setINDIGeoLocation(QString deviceName, double longitude, double latitude)</function
 240 > : Устанавливает географическое положение телескопа: долготу и широту. Долгота устанавливается в нотации "E of N". На пример,долгота города Calgary, Canada в &kstars;: -114 04 58 - широта: 51 02 58. Необходимо преобразовывать <emphasis
 241 >только</emphasis
 242 > отрицательные значения долготы. Чтобы преобразовать долготы в  "E of N" нотацию, мы должны прибавить к абсолютному значению долготы прибавить 180 градусов. Так, в нашем примере, долгота INDI = 114 04 08 + 180 00 00 = 294 04 08 "E of N".</para
 243 ></listitem>
 244         <listitem
 245 ><para
 246 ><function
 247 >setINDIUTC(QString ddeviceName, QString UTCDateTime)</function
 248 > : Установить для телескопа UTC дату и время в вормате ISO 8601, т.е. в формате ГГГГ-ММ-ДДTЧЧ:MM:СС (например 2004-07-12T22:05:32).</para
 249 ></listitem>
 250       </itemizedlist>
 251     </listitem>
 252     <listitem
 253 ><para
 254 >Функции фокусировки (Focuser Functions): функции управляющие фокусировкой телескопа и статусом фокусировки.</para>
 255       <itemizedlist>
 256       <listitem
 257 ><para
 258 ><function
 259 >setINDIFocusSpeed(QString deviceName, QString action)</function
 260 > : Установить скорость фокусирующего механизма. Допустимые значения FOCUS_HALT, FOCUS_SLOW, FOCUS_MEDIUM, и FOCUS_FAST.</para
 261 ></listitem>
 262       <listitem
 263 ><para
 264 ><function
 265 >setINDIFocusTimeout(QString deviceName, int timeout)</function
 266 > : Установить максимальную длительность любых операций выполняемых после в результате вызова функции startINDIFocus.</para
 267 ></listitem>
 268       <listitem
 269 ><para
 270 ><function
 271 >startINDIFocus(QString deviceName, int focusDir)</function
 272 > : Фокусировать на короткое расстояние (focusDir = 0) или на бесконечность (focusDir = 1). Скорость и время устанавливаются функциями <function
 273 >setINDIFocusSpeed()</function
 274 > и <function
 275 >setINDIFocusTimeout()</function
 276 >.</para
 277 ></listitem>
 278     </itemizedlist>
 279     </listitem>
 280     <listitem
 281 ><para
 282 >Функции камеры/ПЗС (Camera/CCD Functions) :функции управляющие камерой/ПЗС и их состоянием.</para>
 283       <itemizedlist>
 284         <listitem
 285 ><para
 286 ><function
 287 >setINDICCDTemp(QString deviceName, int temp)</function
 288 > : Установить температуру ПЗС сенсоров, в градусах Цельсия.</para
 289 ></listitem>
 290         <listitem
 291 ><para
 292 ><function
 293 >setINDIFrameType(QString deviceName, QString type)</function
 294 > : Установить тип кадра ПЗС. Возможные значения: FRAME_LIGHT, FRAME_BIAS, FRAME_DARK, и FRAME_FLAT.</para
 295 ></listitem>
 296         <listitem
 297 ><para
 298 ><function
 299 >startINDIExposure(QString deviceName, int timeout)</function
 300 > : Начать экспозицию ПЗС/Камеры, время (<emphasis
 301 >timeout</emphasis
 302 >) в секундах.</para
 303 ></listitem>
 304       </itemizedlist>
 305     </listitem>
 306   </orderedlist>
 307
 308 <para
 309 >Заметьте, что имя устройства - первый аргумент всех функций INDI. Это позволяет не перемешиваться командам к разным устройствам в одном сценарии. Редактор сценариев две возможности для облегчения написания и редактирования сценариев INDI.</para>
 310 <itemizedlist>
 311   <listitem
 312 ><para
 313 ><option
 314 >Добавить waitForINDIAction после каждого действия INDI</option
 315 > : Если эта опция выбрана, то после любого действия Редактор сценариев добавит команду <function
 316 >waitForINDIAction()</function
 317 >. Например, если вы добавите функцию <function
 318 >switchINDI()</function
 319 >и эта опция была отмечена, редактор сценариев добавит "waitForINDIAction CONNECTION" в сценарий сразу после <function
 320 >switchINDI()</function
 321 >. Это приведёт к приостановке выполнения сценария после <function
 322 >switchINDI()</function
 323 >, покаl <function
 324 >switchINDI()</function
 325 > не вернёт OK (&ie; пока устройство не подключится). Важно знать, что редактор сценариев не добавит <function
 326 >waitForINDIAction()</function
 327 > для действий, добавленных с помощью <function
 328 >setINDIAction()</function
 329 >, так как &kstars; не сможет определить родительское свойство таких действий. Поэтому, вы должны вручную добавить <function
 330 >waitForINDIAction()</function
 331 > после этих действий, если требуется.</para>
 332   </listitem>
 333   <listitem
 334 ><para
 335 ><option
 336 >Повторное использование имён INDI</option
 337 > : Когда эта опция выбрана, то во всех последующих функциях, будет использоваться последнее введённое имя устройства. Новое имя устанавливается с помощью <function
 338 >startINDI()</function
 339 >. Если вы работаете с несколькими устройствами, то рекомендуется выключать эту опцию.</para>
 340   </listitem>
 341 </itemizedlist>
 342
 343 <para
 344 >Теперь мы можем создать пример сценария, который будет управлять телескопом LX200 GPS, и ПЗС камерой Finger Lakes, присоединённой к нему. Наш пример очень прост. Мы повернём телескоп и проследим за Марсом, и сделаем три снимка с экспозицией 10с через 20с каждый.</para>
 345 <important
 346 ><para
 347 >У нас нет средств обратной связи или слежения в INDI DCOP интерфейсе, чтобы узнать степень выполнения операции (за исключением функции <function
 348 >waitForINDIAction()</function
 349 >), поэтому мы должны постоянно следить за устройством. Так как мы не можем следить за возникновением ошибок, и исправлять их "на лету", мы должны писать сценарий с перестраховкой. Все сценарии должны тщательно проверяться, перед их использованием.</para
 350 ></important>
 351
 352 <screenshot>
 353   <screeninfo
 354 >Редактор сценариев </screeninfo>
 355   <mediaobject>
 356     <imageobject>
 357       <imagedata fileref="indiscript.png" format="PNG"/>
 358     </imageobject>
 359     <textobject>
 360       <phrase
 361 >Редактор сценариев</phrase>
 362     </textobject>
 363   </mediaobject>
 364 </screenshot>
 365
 366 <para
 367 >Пример сценария приведён выше. Обратите внимание, что отмечена опция <option
 368 >Добавить waitForINDIAction после каждого действия INDI</option
 369 > и не отмечена <option
 370 >Повторное использование имён INDI</option
 371 >. Первая функция - <function
 372 >startINDI()</function
 373 >. Мы запускаем наше устройство локально, поэтому нет необходимости менять режим сервиса в окне аргументов функций. Мы вводим имена устройств, начиная с телескопа "LX200 GPS", потом повторяем тоже и для ПЗС матрицы - "FLI CCD".После этого стоит функция <function
 374 >waitFor()</function
 375 >. Рекомендуется использовать функцию <function
 376 >waitFor()</function
 377 > непосредственно после <function
 378 >startINDI()</function
 379 >, чтобы приостановить выполнение сценария на 1-5с. Это сделано для того, чтобы быть уверенными, что внутренние переменные настроены так как надо, и устройства готовы для получения команд. Также это необходимо для управления удалёнными устройствами, так как связь ними может быть затруднена. Далее следует функция <function
 380 >switchINDI()</function
 381 >, чтобы соединиться с устройствами.</para>
 382
 383 <para
 384 >Так как опция <option
 385 >Добавить waitForINDIAction после каждого действия INDI</option
 386 > отмечена, то нет необходимости добавлять <function
 387 >waitForINDIAction()</function
 388 > после <function
 389 >switchINDI()</function
 390 >, чтобы убедиться в выполнении команды, потому что редактор сценариев сделает это автоматически при сохранении файла. Далее запустим слежение телескопа, добавив <function
 391 >setINDIScopeAction()</function
 392 > с аргументом TRACK. Заметьте, что мы переводим телескоп в режим слежения <emphasis
 393 >перед</emphasis
 394 > указанием координат. Функция <function
 395 >setINDIScopeAction()</function
 396 > применена здесь для большего удобства, можно было воспользоваться функцией <function
 397 >setINDIAction()</function
 398 > с ключевым словом TRACK. Тем не менее, благодаря использования <function
 399 >setINDIScopeAction()</function
 400 > &kstars; автоматически добавит функцию <function
 401 >waitForINDIAction()</function
 402 >. </para>
 403
 404 <para
 405 >Далее мы используем функцию <function
 406 >setINDITargetName()</function
 407 >, с "целью" - Марс. И, напоследок, получим снимки с экспозицией 10с, используя <function
 408 >startINDIExposure()</function
 409 >, с паузой в 20с между снимками используя <function
 410 >waitFor()</function
 411 > со значением аргумента 20.</para>
 412
 413 <para
 414 >Теперь сохраним сценарий, чтобы использовать его в дальнейшем. Сохранённый сценарий должен выглядеть примерно так:</para>
 415 <blockquote
 416 ><programlisting
 417 >#!/bin/bash
 418     #KStars DCOP script: Demo Script
 419     #by Jasem Mutlaq
 420     #last modified: Thu Jan 6 2005 09:58:26
 421     #
 422     KSTARS=`dcopfind -a 'kstars*'`
 423     MAIN=KStarsInterface
 424     CLOCK=clock#1
 425     dcop $KSTARS $MAIN  startINDI "LX200 GPS" true
 426     dcop $KSTARS $MAIN  startINDI "FLI CCD" true
 427     dcop $KSTARS $MAIN  waitFor 3
 428     dcop $KSTARS $MAIN  switchINDI "LX200 GPS" true
 429     dcop $KSTARS $MAIN  waitForINDIAction "LX200 GPS" CONNECTION
 430     dcop $KSTARS $MAIN  switchINDI "FLI CCD" true
 431     dcop $KSTARS $MAIN  waitForINDIAction "FLI CCD" CONNECTION
 432     dcop $KSTARS $MAIN  setINDIScopeAction "LX200 GPS" TRACK
 433     dcop $KSTARS $MAIN  waitForINDIAction "LX200 GPS" ON_COORD_SET
 434     dcop $KSTARS $MAIN  setINDITargetName "LX200 GPS" Mars
 435     dcop $KSTARS $MAIN  waitForINDIAction "LX200 GPS" EQUATORIAL_EOD_COORD
 436     dcop $KSTARS $MAIN  startINDIExposure "FLI CCD" 10
 437     dcop $KSTARS $MAIN  waitForINDIAction "FLI CCD" EXPOSE_DURATION
 438     dcop $KSTARS $MAIN  waitFor 20
 439     dcop $KSTARS $MAIN  startINDIExposure "FLI CCD" 10
 440     dcop $KSTARS $MAIN  waitForINDIAction "FLI CCD" EXPOSE_DURATION
 441     dcop $KSTARS $MAIN  waitFor 20
 442     dcop $KSTARS $MAIN  startINDIExposure "FLI CCD" 10
 443     dcop $KSTARS $MAIN  waitForINDIAction "FLI CCD" EXPOSE_DURATION
 444 </programlisting>
 445 </blockquote>
 446 </sect2>
 447 </sect1>
 448