# A Ferramenta de Construção de 'Scripts'

As aplicações do KDE podem ser controladas externamente a partir de outro programa, de uma linha de comandos da consola ou a partir de um 'script', usando o Desktop COmmunication Protocol (DCOP). O KStars tira partido desta funcionalidade para permitir que comportamentos mais complexos possam ser usados em 'scripts' e reproduzidos em qualquer altura. Isto pode ser usado, por exemplo, para criar uma demonstração para uma aula que ilustre um conceito astronómico.

O problemas com os programas do DCOP é que escrevê-los é de certa forma uma espécie de programação, o que poderá ser uma tarefa complicada para aqueles que não têm experiência nenhuma em programação. A Ferramenta de Construção de 'Scripts' oferece uma interface GUI para criar programas ou 'scripts' de DCOP, facilitando a criação de programas complexos.

## Introdução ao Construtor de 'Scripts'

Antes de explicar como usar o Construtor de 'Scripts', será dada uma introdução muito breve a todos os componentes GUI; para mais informações, use a função de "O Que É Isto?".

A Ferramenta de Construção de 'Scripts'
Ferramenta de Construção de 'Scripts'

O Construtor de 'Scripts' é apresentado na imagem acima. A área à esquerda é a do 'Script' Actual; ela mostra a lista dos comandos que compõem o 'script' em elaboração. A zona da direita é o Navegador de Funções; ela mostra uma lista com todas as funções de 'scripts' disponíveis. Por baixo do Navegador de Funções, existe um pequeno painel que irá mostrar uma documentação curta sobre a função seleccionada no Navegador de Funções. O painel por baixo do 'Script' Actual é o painel dos Argumentos da Função; quando for seleccionada uma função no 'Script Actual', este painel irá conter os itens para indicar os valores dos argumentos que a função seleccionada necessita.

Ao longo do topo da janela, existe uma fila de botões que lidam com o 'script' como um todo. Da esquerda para a direita, eles são: Novo 'Script', Abrir um 'Script', Gravar 'Script', Gravar o 'Script' Como... e Testar 'Script'. A função destes botões deverá ser óbvia, talvez exceptuando o último botão. Se carregar em Testar 'Script', o 'script' actual tentará ser executado na janela principal do KStars. Você deverá mover a janela do Construtor do 'Script' da frente antes de carregar nisto, para que possa ver os resultados.

No centro da janela, existe uma coluna de botões que operam em funções individuais do 'script'. De cima para baixo, estas são: Adicionar Função, Remover Função, Copiar Função, Subir e Descer. O Adicionar Função adiciona a função seleccionada de momento no Navegador de Funções na zona do 'Script' Actual (você poderá também adicionar uma função se fizer duplo-click nela). O resto dos botões lidam com a função seleccionada no 'Script Actual', removendo-a, duplicando-a ou mudando a sua posição no 'script' actual.

## Utilizar o Construtor de 'Scripts'

Para ilustrar a utilização do Construtor de 'Scripts', iremos apresentar um pequeno exemplo de tutorial onde iremos criar um 'script' que segue a Lua enquanto o relógio anda a uma velocidade acelerada.

Se vamos seguir a Lua, teremos de apontar a visualização para ela em primeiro lugar. A função lookToward é usada para isso. Seleccione esta função no Navegador de Funções, tendo em atenção a documentação que é mostrada no painel por baixo do Navegador. Carregue no botão Adicionar Função para adicionar esta função à área do 'Script Actual'. O painel dos Argumentos da Função irá conter agora uma lista chamada dir, que é uma abreviatura de 'direction' (direcção). Esta a direcção para a qual a visualização deverá ser apontada. A lista contém apenas os pontos cardeais, não a Lua ou outros objectos quaisquer. Você poderá então escrever Lua na opção manualmente, ou carregar no botão Objecto para usar a janela de Procurar um Objecto para seleccionar a Lua da lista de objectos identificados. Repare que, como de costume, o foco num objecto activa automaticamente o modo de seguimento do objecto, por isso não há necessidade de adicionar a função setTracking depois do 'lookToward'.

Agora que já tratámos de apontar para a Lua, queremos fazer o tempo passar a uma velocidade acelerada. Use a função setClockScale para isso. Adicione-a ao 'script' fazendo duplo-click nela no Navegador de Funções. O painel de Argumentos da Função contém um selector para indicar a iteração temporal desejada para o relógio da simulação. Mude essa iteração para 3 horas.

OK, já apontámos para a Lua e acelerámos o relógio. Agora só queremos que o 'script' espere durante vários segundos enquanto a visualização persegue a Lua. Adicione a função waitFor ao 'script' e use o painel de Argumentos da Função para indicar que deverá esperar 20 segundos antes de continuar.

Para terminar, vamos repor a iteração temporal do relógio para o valor normal de 1 segundo. Adicione outra instância do 'setClockScale', e coloque o seu valor a 1 s.

De facto, ainda não terminámos realmente. Temos provavelmente que nos certificar a visualização está a usar coordenadas Equatoriais antes de o 'script' seguir a Lua com uma iteração temporal acelerada. Caso contrário, se a visualização estiver a usar coordenadas Horizontais, ela irá rodar muito depressa, com ângulos grandes, à medida que a Lua nasce e se põe. Isto poderá ser muito confuso, e é evitado se usar a opção de visualização UseAltAz igual a false. Para mudar uma opção de visualização qualquer, use a função changeViewOption. Adicione esta função ao 'script' e analise o painel dos Argumentos da Função. Existe uma lista que contém todas as opções de visualização que poderão ser ajustadas com o 'changeViewOption'. Dado que sabemos que queremos usar a opção UseAltAz, poderemos simplesmente seleccioná-la na lista. Contudo, a lista é muito grande, e não existe nenhuma explicação para que é que serve cada item. Por isso poderá ser mais fácil carregar no botão Árvore de Navegação, o qual irá abrir uma janela que contém uma árvore com todas as opções de visualização, organizadas por tópico. Para além disso, cada item tem uma breve explicação do que é que a opção faz e o tipo de dados do valor da opção. A opção UseAltAz encontra-se sob a categoria Opções do mapa do céu. Basta seleccionar este item e carregar em OK, para que fique seleccionado na lista do painel dos Argumentos da Função. Finalmente, coloque o seu valor a false ou a 0.

Um passo mais: a alteração do 'UseAltAz' no fim do 'script' não nos faz nada bem; precisamos que isto seja alterado antes que algo de mau aconteça. Por isso, certifique-se que esta função é seleccionada na janela do 'Script Actual' e carregue no botão Subir até que seja a primeira função.

Agora que terminámos o 'script', deveremos gravá-lo em disco. Carregue no botão Gravar 'Script'. Isto irá abrir em primeiro lugar uma janela onde poderá indicar um nome para o 'script' e preencher o seu nome como autor. Indique como nome Seguir a Lua e o seu nome como autor, carregando depois em OK. De seguida, você irá ver a janela normal de Gravar um Ficheiro do &kde;. Indique o nome do ficheiro do 'script' e carregue em OK para gravar o código. Repare que, se o seu ficheiro não terminar em .kstars, este sufixo será adicionado automaticamente. Se você for curioso, poderá examinar o ficheiro do 'script' com um editor de texto qualquer.

Agora que temos um 'script' completo, poderemos corrê-lo de várias formas. Numa linha de comandos da consola, você poderá simplesmente executar o 'script', desde que esteja aberta uma instância do KStars em execução. Em alternativa, você poderá executar o programa no KStars com o item Executar 'Script' do menu Ficheiro.

## Automação do Dispositivo com o INDI

O escalonamento e automação do dispositivo é suportado por todos os dispositivos compatíveis com o INDI. Poderá coordenar qualquer número de dispositivos para efectuar operações complexas com o Construtor de 'Scripts' do &kstars;. Isto poderá ser feito se usar a interface DCOP do INDI do &kstars;, que oferece várias classes de funções diferentes para se adequar às suas tarefas. As funções de DCOP do INDI poderão ser decompostas em quatro diferentes classes. Segue-se uma revisão das funções e dos seus argumentos, tal como são suportadas no KStars. É altamente recomendado que leia a secção de Conceitos do INDI, dado que serão aplicados conceitos-chave do INDI ao longo deste tutorial.

1. Funções Genéricas do Dispositivo: Funções para estabelecer/desligar os dispositivos, etc.

   - `startINDI (QString nomeDispositivo, bool usoLocal)` : Estabelece um serviço do INDI quer como local quer como servidor.

   - `shutdownINDI (QString nomeDispositivo)` : Desliga o serviço do INDI.

   - `switchINDI(QString nomeDispositivo, bool ligar)` : Liga ou desliga um dispositivo do INDI.

   - `setINDIPort(QString nomeDispositivo, QString porto)` : Indica o porto de ligação do dispositivo.

   - `setINDIAction(QString nomeDispositivo, QString accao)` : Activa uma acção do INDI. A acção poderá ser qualquer elemento de uma propriedade de opção

   - `waitForINDIAction(QString nomeDispositivo, QString accao)` : Coloca a execução do programa em pausa até que a acção propriedade da acção indicada seja devolvida com um estado OK.

2. Funções do Telescópio: Funções para controlar o movimento e o estado do telescópio.

   - `setINDIScopeAction(QString nomeDispositivo, QString accao)` : Muda o modo ou a acção do telescópio. As opções disponíveis são a SLEW, TRACK, SYNC, PARK e a ABORT.

   - `setINDITargetCoord(QString nomeDispositivo, double AR, double DEC)` : Define as coordenadas-alvo JNow do telescópio para uma dada AR e DEC.

   - `setINDITargetName(QString nomeDispositivo, QString nomeObjecto)` : Configura as coordenadas-alvo JNow do telescópio para as coordenadas do nomeObjecto. O KStars irá procurar o nome do objecto na sua base de dados e irá obter a AR e a Dec deste, se for encontrado.

   - `setINDIGeoLocation(QString nomeDispositivo, double longitude, double latitude)` : Configura a localização geográfica do telescópio para a latitude e longitude indicadas. A longitude é medida a partir de Greenwich, no Reino-Unido, para Este. Contudo, embora seja comum usar longitudes negativas para o hemisfério ocidental, o INDI está à espera de valores de longitude entre 0 e 360 graus. Como tal, se estiver uma longitude negativa, basta adicionar 360 graus para obter o valor esperado pelo INDI. Por exemplo, as coordenadas de Calgary, no Canadá, correspondem no &kstars; à longitude: -114 04 58 - latitude: 51 02 58. Como tal, o INDI iria necessitar da longitude = 360 - 114,083 = 245,917 graus.

   - `setINDIUTC(QString nomeDispositivo, QString dataHomeUTC)` : Configura a data e hora UTC do telescópio no formato ISO 8601. O formato é igual a AAAA-MM-DDTHH:MM:SS (p.ex. 2004-07-12T22:05:32).

3. Funções da Câmara/CCD: Funções para controlar as propriedades e o estado da câmara/CCD.

   - `setINDICCDTemp(QString nomeDispositivo, int temp)` : Configura a temperatura-alvo do 'chip' CCD em graus Celsius (centígrados).

   - `setINDIFrameType(QString nomeDispositivo, QString tipo)` : Configura o tipo de imagem do CCD. As opções disponíveis são FRAME_LIGHT, FRAME_BIAS, FRAME_DARK e FRAME_FLAT.

   - `startINDIExposure(QString nomeDispositivo, int tempoLimite)` : Inicia a exposição do CCD/Câmara durante o período em segundos indicado em tempoLimite.

4. Funções do Sistema de Foco: Funções para controlar o movimento e o estado do sistema de foco.

   - `setINDIFocusSpeed(QString nomeDispositivo, QString accao)` : Configura a velocidade do sistema de foco. As opções disponíveis são a FOCUS_HALT, FOCUS_SLOW, FOCUS_MEDIUM e a FOCUS_FAST.

   - `setINDIFocusTimeout(QString nomeDispositivo, int tempoLimite)` : Configura a duração em segundos para quaisquer operações subsequentes do 'startINDIFocus'.

   - `startINDIFocus(QString nomeDispositivo, int dirFoco)` : Move o sistema de foco quer para dentro (dirFoco = 0) quer para fora (dirFoco = 1). A velocidade e a duração desta operação é definida pelas funções `setINDIFocusSpeed()` e `setINDIFocusTimeout()`.

5. Funções do Filtro: Funções para controlar a posição do filtro.

   - `setINDIFilterNum(QString nomeDispositivo, int num_filtro)` : Muda a posição do filtro para `num_filtro`. O utilizador poderá atribuir nomes alternativos aos números dos filtros na janela para Configurar o INDI, no menu Dispositivos (p.ex. Filtro 1 = Vermelho, Filtro 2 = Verde..etc).

Repare que o nome do dispositivo é o primeiro argumento de todas as funções do INDI. Isto permite vários comandos que são enviados para dispositivos INDI diferentes serem interligados em conjunto num programa. A ferramenta de Construção de 'Scripts' oferece duas opções para facilitar a criação e a edição dos programas INDI:

- `Adicionar waitForINDIAction após qualquer acção do INDI` : Quando estiver assinalada esta opção, a ferramenta do Construtor de 'Scripts' irá adicionar automaticamente um `waitForINDIAction()` depois de cada acção que reconhecer. Por exemplo, se adicionar a função `switchINDI()` ao programa e esta opção estiver assinalada, o Construtor do 'Script' irá adicionar um "waitForINDIAction CONNECTION" no ficheiro do 'script' logo a seguir ao `switchINDI()`. Isto fará com que o 'script' entre em pausa depois de emitir o `switchINDI()`, até que o `switchINDI()` devolva um estado OK (&ie; a ligação ao dispositivo foi bem-sucedida). É de importância crítica saber que o Construtor do 'Script' não poderá adicionar automaticamente o `waitForINDIAction()` para as acções genéricas adicionadas com a função `setINDIAction()`. Isto deve-se ao facto de o KStars não conseguir determinar a propriedade 'parent' das acções genéricas. Como tal, terá de adicionar manualmente o `waitForINDIAction()` a seguir às acções genéricas, sempre que tal for desejado.

- `Reutilizar o nome do dispositivo INDI` : Quando estiver assinalada, o campo do nome do dispositivo de todas as funções subsequentes é preenchido automaticamente com o último nome de dispositivo. Este último nome é preenchido de cada vez que a função `startINDI()` é adicionada ao programa actual. Ao trabalhar com vários dispositivos, recomenda-se ter esta opção desligada.

Agora, está tudo pronto para criar um programa de demonstração que controla o telescópio GPS LX200, para além da câmara CCD Finger Lakes. A tarefa será simples. Vai-se pedir ao telescópio para apontar e seguir Marte, pelo que se pede depois à câmara para tirar três fotografias de 10 segundos, separadas por 20 segundos.

Dado que não existe nenhuma reacção na interface de DCOP do INDI sobre o progresso, o valor ou o estado das operações e parâmetros do dispositivo (excepto no `waitForINDIAction()`), a automação do dispositivo no KStars é semelhante a um sistema de controlo com uma malha aberta. Nestes sistemas, não existe normalmente qualquer reacção directa para medir o progresso do sistema e para corrigir os seus erros. Por consequência, terá de desenhar os seus programas de automação do dispositivo com uma consideração cuidadosa. Todos os programas de automação deverão ser sujeitos a testes rigorosos antes da instalação.

A Ferramenta de Construção de 'Scripts'
Ferramenta de Construção de 'Scripts'

O programa de demonstração é mostrado na imagem acima. Repare que a opção `"Adicionar o waitForINDIAction após qualquer acção do INDI"` está ligada e a `"Reutilizar o nome do dispositivo INDI"` está desligada. A primeira função a adicionar é a `startINDI()`, tal como é demonstrado acima. Os dispositivos vão ser corridos de forma local, como tal não serão alterado o modo de serviço fornecido na janela de argumento da função. Será indicado o nome do dispositivo, a começar pelo telescópio "LX200 GPS". A mesma operação será repetida para o "FLI CCD". Existe uma função `waitFor()` a seguir a isso. Recomenda-se geralmente o uso da função `waitFor()` logo a seguir ao `startINDI()` para parar o programa durante 1-5 segundos. Isto irá garantir que todas as propriedades são criadas e que estão prontas para receber comandos. Também é útil para controlar dispositivos remotos, dado que a obtenção e criação de propriedades poderá levar algum tempo. Na próxima função, a `switchINDI()`, vai-se estabelecer a ligação a cada dispositivo.

Dado que a opção `"Adicionar o waitForINDIAction após qualquer acção do INDI"` está assinalada, não é necessário adicionar um `waitForINDIAction()` depois do `switchINDI()` para garantir que só se continua a execução do programa após uma ligação com sucesso. Isto acontece porque a ferramenta do Construtor de 'Scripts' fará isso automaticamente pelo utilizador, quando gravar o programa. Agora, vai-se colocar o modo do telescópio em seguimento, carregando para tal na função `setINDIScopeAction()` e seleccionando o TRACK. Lembre-se que necessita de colocar o telescópio no modo de seguimento antes de emitir as coordenadas que ele irá seguir. A função `setINDIScopeAction()` é oferecida por conveniência, dado que, neste exemplo, ela emite apenas uma função genérica `setINDIAction()`, seguida da palavra-chave TRACK. Contudo, o benefício de usar o `setINDIScopeAction()` é que o KStars poderá adicionar automaticamente um `waitForINDIAction()` a seguir, quando for necessário. Esta funcionalidade não fica disponível automaticamente para as acções genéricas, tal como foi discutido anteriormente.

A seguir, será usada a função `setINDITargetName()` para apontá-lo para Marte. Finalmente, os últimos passos envolvem a captura de uma imagem durante 10 segundos, o qual poderá ser feito com a função `startINDIExposure()`, esperando 20 segundos entre cada uma, o que poderá também ser feito com a função `waitFor()` com um valor igual a 20.

Poder-se-á agora gravar o programa e executá-lo em qualquer altura. O programa gravado será semelhante ao seguinte:

>     #!/bin/bash
>         #Programa de DCOP do KStars: Programa de Demonstração
>         #de Jasem Mutlaq
>         #última modificação: Qui 6 Jan 2005 09:58:26
>         #
>         KSTARS=`dcopfind -a 'kstars*'`
>         MAIN=KStarsInterface
>         CLOCK=clock#1
>         dcop $KSTARS $MAIN  startINDI "LX200 GPS" true
>         dcop $KSTARS $MAIN  startINDI "FLI CCD" true
>         dcop $KSTARS $MAIN  waitFor 3
>         dcop $KSTARS $MAIN  switchINDI "LX200 GPS" true
>         dcop $KSTARS $MAIN  waitForINDIAction "LX200 GPS" CONNECTION
>         dcop $KSTARS $MAIN  switchINDI "FLI CCD" true
>         dcop $KSTARS $MAIN  waitForINDIAction "FLI CCD" CONNECTION
>         dcop $KSTARS $MAIN  setINDIScopeAction "LX200 GPS" TRACK
>         dcop $KSTARS $MAIN  waitForINDIAction "LX200 GPS" ON_COORD_SET
>         dcop $KSTARS $MAIN  setINDITargetName "LX200 GPS" Mars
>         dcop $KSTARS $MAIN  waitForINDIAction "LX200 GPS" EQUATORIAL_EOD_COORD
>         dcop $KSTARS $MAIN  startINDIExposure "FLI CCD" 10
>         dcop $KSTARS $MAIN  waitForINDIAction "FLI CCD" EXPOSE_DURATION
>         dcop $KSTARS $MAIN  waitFor 20
>         dcop $KSTARS $MAIN  startINDIExposure "FLI CCD" 10
>         dcop $KSTARS $MAIN  waitForINDIAction "FLI CCD" EXPOSE_DURATION
>         dcop $KSTARS $MAIN  waitFor 20
>         dcop $KSTARS $MAIN  startINDIExposure "FLI CCD" 10
>         dcop $KSTARS $MAIN  waitForINDIAction "FLI CCD" EXPOSE_DURATION

A biblioteca do INDI oferece ferramentas de programação robustas quer permitem aos programadores orquestrarem programas muito complexos. Para mais detalhes, veja o Manual de Programador do INDI.