Criação de Módulos no VisTrails

Criação de Módulos no VisTrails A criação de módulos no VisTrails não é trivial. Não há no programa algum botão ou janela que promova o desenvolvimento deles. Existem duas formas de criá-los; uma delas é fazer o módulo dentro do arquivo basic_modules.py ; a outra é criar um novo arquivo para o módulo (forma mais organizada e limpa); logo, para as duas maneiras, é necessário que a pessoa saiba Python, a linguagem de programação usada nesse aplicativo. Para que seja criado um novo módulo, ele pode ser definido no arquivo basic_modules.py, o qual se encontra no diretório Arquivos de Programas\VisTrails\vistrails\core\modules. O novo módulo deverá ser uma classe derivada da classe Modules, que define suas funcionalidades básicas. Veja o exemplo abaixo: class Soma(Module): def compute(self): v=self.getinputfromport("parcela1")+self.getinputfromport("parcela2") self.setresult("soma",v) self.setresult("somacomostring",str(v)) _reg.add_module(soma) _reg.add_input_port(soma, parcela1,integer) _reg.add_input_port(soma, parcela2,integer) _reg.add_output_port(soma, soma,integer) _reg.add_output_port(soma, somacomostring,string) O nome do módulo, como se pode observar, é Soma (é definido pelo nome da classe). A função compute() define basicamente as relações entre as entradas ( parcela1 e parcela2 ) e as saídas ( soma e somacomostring ), assim como todas as operações necessárias para essas relações; as entradas e as saídas, por sua vez, são chamadas de portas. O método getinputfromport obtém o valor da entrada desejada (o nome da porta de entrada é o parâmetro que fica entre parênteses), que, assim, pode ser armazenada; o método setresult, por sua vez, define o valor de uma saída (no caso do exemplo acima, define o valor das portas de saída soma e somacomostring ). Dessa forma, o módulo Soma implementa a adição de dois números, cujo resultado é apresentado, ou como um número inteiro ( soma ), ou como uma string ( somacomostring ). Há ainda outros métodos que não foram implementados acima, como o hasinputfromport, que verifica se o parâmetro de uma porta de entrada foi determinado. Para que esse novo módulo seja finalmente inserido no VisTrails, é necessário adicionar as linhas de registro para ele (elas estão definidas no arquivo module_registry.py, que se encontra no mesmo diretório do basic_modules.py ). A linha _reg.add_module adiciona o determinado módulo no programa; a linha _reg.add_input_port determina uma porta de entrada para o módulo (é preciso determinar qual módulo receberá essa porta, o seu nome e o seu tipo); a linha _reg.add_output_port, por outro lado, cria uma porta de saída (também deverão ser determinados o módulo, o nome e seu tipo, assim como em _reg.add_input_port ). Depois de feito tudo isso, o módulo é criado e aparece na lista do VisTrails, dentro de Basic Modules, podendo ser, então, utilizado. Existe outra forma de criar módulos no VisTrails que não depende do arquivo basic_modules.py. Nessa forma, o usuário cria um package, como o Basic Modules, que seria um conjunto de vários módulos. Para isso, é necessário criar um arquivo novo dentro da

pasta package, a qual se encontra no diretório Arquivos de programas\vistrails\vistrails. Veja o exemplo abaixo do arquivo Testes VisTrails_PESC.py : import core.modules.module_registry from core.modules.vistrails_module import Module version="1.0" name="testes VisTrails_PESC" identifier="ufrj.vistrails_pesc.testes" class ReadFile (Module): "ReadFile eh um modulo que le um arquivo (tem como entrada o diretorio desse arquivo)." def compute(self): d=self.getinputfromport("diretorio") arq=open(d,"r") s=arq.read() self.setresult("string",s) class WriteFile (Module): "WriteFile eh um modulo que escreve em um arquivo uma string determinada pelo usuario." def compute(self): d=self.getinputfromport("diretorio") s=self.getinputfromport("string") arq=open(d,"w") arq.write(s) arq.close() arq2=open(d) self.setresult("arquivo",arq2) ################################################################################### def initialize(*args,**keywords): reg=core.modules.module_registry.registry reg.add_module(readfile) reg.add_input_port(readfile,"diretorio",(core.modules.basic_modules.string," o diretorio do arquivo")) reg.add_output_port(readfile,"string",(core.modules.basic_modules.string,"a string do arquivo")) reg.add_module(writefile) reg.add_input_port(writefile,"diretorio",(core.modules.basic_modules.string, "o diretorio do arquivo")) reg.add_input_port(writefile,"string",(core.modules.basic_modules.string,"a string a ser escrita")) reg.add_output_port(writefile,"arquivo",(core.modules.basic_modules.file,"o arquivo modificado"),optional=true) As duas primeiras linhas são comandos que sempre devem ser chamados; dizem respeito a importações necessárias para o funcionamento dos módulos. Logo abaixo, os campos version, name e identifier são usados para caracterizar o package que está sendo criado: version será a versão do package; name será o seu nome; e identifier diz respeito à instituição/pessoa que o desenvolveu. Após caracterizar o package, devem ser desenvolvidos os seus módulos. O esquema é o mesmo já mostrado anteriormente. No caso do exemplo acima, o módulo ReadFile é usado para ler um determinado arquivo de entrada, colocando na saída o seu conteúdo em string; o módulo WriteFile escreve em um arquivo determinado pelo usuário uma string desejada (os conceitos de entrada e saída de arquivos, usados nesses dois módulos, serão melhor explicados no próximo tópico). A única diferença entre essa forma e a outra é que as linhas de comando necessárias para adicionar os módulos e as portas devem ser feitas em uma nova função, chamada de initialize(*args,**keywords).

Após desenvolver esse arquivo e salvá-lo, o package não é incorporado automaticamente na lista Modules do programa; é necessário habilitá-lo dentro do VisTrails; para isso, é só clicar em Edit e depois em Preferences... ; na aba Module Packages, o usuário pode habilitar/desabilitar diversos packages, inclusive aquele criado por ele. Na maioria das vezes, desejamos visualizar a saída dos módulos que criamos através do Spreadsheet, a janela de visualização do VisTrails; isso pode ser muito importante para determinados workflows. Assim, existem algumas alternativas encontradas para que isso ocorra, e elas seguem abaixo. O módulo RichTextCell e a criação de arquivos temporários A visualização pode ser feita utilizando-se o módulo RichTextCell, que transmite um arquivo do bloco de notas ou um HTML para o Spreadsheet. Para que isso aconteça, o módulo deve ter uma saída do tipo File, já que é o tipo de entrada aceito pelo RichTextCell. Logo, utilizando conceitos de entrada e saída de arquivos, e também um recurso provido pelo VisTrails, a criação de arquivos temporários, pode-se desenvolver uma visualização. Abaixo, encontra-se um exemplo de módulo usando esses novos conceitos: class arquivo(module): def compute(self): v=self.getinputfromport( parcela1 )+self.getinputfromport( parcela2 ) resultado=self.interpreter.filepool.create_file(suffix=.txt ) arq=open( resultado.txt, w ) arq.write(str(v)) arq.close() x=open( resultado.txt ) self.setresult( file,x) def initialize(*args,**keywords): reg=core.modules.module_registry.registry reg.add_module(arquivo) reg.add_input_port(arquivo, parcela1,core.modules.basic_modules.integer) reg.add_input_port(arquivo, parcela2,core.modules.basic_modules.integer) reg.add_output_port(arquivo, file,core.modules.basic_modules.file) Esse módulo simplesmente implementa a função de adição já vista anteriormente: você escolhe dois números do tipo inteiro (que, no exemplo acima, são os parâmetros de entrada parcela1 e parcela2 ) e o resultado é a soma entre eles (variável v ). Como precisamos desenvolver uma saída do tipo File, que deverá conter o resultado da soma para que ele apareça no Spreadsheet, é necessário criar um arquivo que tenha o valor desse resultado. Para isso, usamos um recurso que o próprio VisTrails oferece, que é a criação de arquivos temporários, feita através de uma linha de comando. A linha de comando é a seguinte: resultado=self.interpreter.filepool.create_file(suffix=".txt") Ela cria um arquivo temporário, que, no caso acima, será um arquivo do bloco de notas com o nome de resultado.txt (a extensão é determinada pelo suffix ). Após a sua criação, devemos abri-lo, de modo que possamos alterá-lo; no caso do módulo arquivo, o resultado.txt será a variável arq. Para que se possa escrever nele o resultado da adição, usamos o método write, que tem como parâmetro justamente o que se deseja escrever. Para que o resultado realmente fique no arquivo, é necessário fechá-lo ( close ) logo em

seguida. Depois, abrimo-lo de novo para que ele seja associado à porta de saída, que, nesse caso, tem o nome de file ( self.setresult( file,x) ). Não se pode esquecer-se de que a saída não será do tipo Integer, e sim do tipo File, a ser determinado nas linhas de registro. Com isso, essa saída pode ser facilmente ligada ao módulo RichTextCell, e o resultado, ou seja, o arquivo temporário criado, aparecerá no Spreadsheet. A criação do arquivo temporário dentro de um módulo, quando necessário, é bem útil e interessante, pois, caso seja preciso passar esse módulo para outra pessoa, ela não necessita ter um determinado arquivo dentro do seu computador para que esse módulo funcione, já que os arquivos temporários serão criados em qualquer máquina. Porém, apesar dessa aplicação ter suas vantagens, ela pode ficar inviável para workflows maiores e mais complexos, pois, dessa forma, o programa pode ficar pesado com tantos arquivos sendo gerados. Assim, a criação de módulos que já transfiram diretamente as saídas para o Spreadsheet fica mais viável e rápido. Essa utilização encontra-se especificada a seguir. Criando módulos SpreadsheetCell A criação de módulos que já transmitam a saída diretamente para o Spreadsheet é menos trivial do que as outras; porém, a sua utilização é de grande necessidade e ajuda para muitas aplicações. Inicialmente, deve-se criar uma pasta, em um diretório específico, que será o local onde serão criados os arquivos para o determinado módulo. Esse diretório é: Arquivos de programas\vistrails\vistrails\packages\spreadsheet\widgets. O nome da pasta não precisa ser necessariamente o nome do módulo, mas recomenda-se que isso seja feito, para evitar confusões. Dentro dessa pasta criada, deverá ser gerado um arquivo de extensão.py (arquivo do Python) que implemente as funções necessárias para o módulo. Veja um exemplo de um arquivo desses a seguir: from core.modules.vistrails_module import Module from PyQt4 import QtCore, QtGui from packages.spreadsheet.basic_widgets import SpreadsheetCell from packages.spreadsheet.spreadsheet_cell import QCellWidget class AdditionSpreadsheet(SpreadsheetCell): def compute(self): p1=self.getinputfromport( parcela1 ) p2=self.getinputfromport( parcela2 ) v=p1+p2 self.display(additionspreadsheetwidget, (str(v),)) class AdditionSpreadsheetWidget(QCellWidget): def init (self, parent=none): QCellWidget. init (self, parent) self.setlayout(qtgui.qvboxlayout(self)) self.browser = QtGui.QTextEdit() self.layout().addwidget(self.browser) def updatecontents(self, inputports): (v,) = inputports self.browser.setplaintext(str(v)) self.browser.setreadonly(true) As importações iniciais ( from...import... ) são necessárias para que o módulo seja criado; elas são encontradas em todos os outros módulos equivalentes. Pode também haver

outras importações, dependendo do módulo que se deseja criar, por necessitar de mais recursos, por exemplo. A primeira classe a ser criada é aquela que definirá as funções do módulo, e, portanto, deve ter o mesmo nome desejado para o módulo; ela deve ser derivada da classe SpreadsheetCell, a qual envia as saídas para o Spreadsheet, mas não determina como elas serão mostradas. Nesse caso, foi implementada a mesma função de soma já vista antes. É necessário haver, no final da função compute, a linha de comando que passa o parâmetro de saída para a janela do módulo no Spreadsheet ( self.display(name, (p,)), em que name é o nome da janela e p é o parâmetro da saída, que precisa ficar em uma tupla). Essa janela do módulo é criada por uma classe que deve ser definida no mesmo arquivo, como será mostrado em seguida. A classe que cria a janela no Spreadsheet pode ter o mesmo nome do módulo, acrescido de Widget no final. Isso não é obrigatório, mas recomenda-se fazer dessa maneira. Ela deve derivar da classe QCellWidget. Essa última classe criada deve ter basicamente duas funções (métodos): init (self) e updatecontents(self,inputports). A primeira define a visualização no Spreadsheet através das classes e métodos do QtGui ; no caso do exemplo acima, foi usada a classe QTextEdit(), que serve para manipular textos (strings) na janela de visualização. Já a segunda função serve para capturar o parâmetro que se quer colocar no Spreadsheet, através da tupla inputports, e para definir os métodos da classe escolhida na primeira função; no exemplo acima, foram escolhidos dois métodos da classe QTextEdit : setplaintext(p), o qual coloca a string p dentro da janela de visualização, e setreadonly(boolean value), o qual define se haverá interação com a string dentro do Spreadsheet (edição, por exemplo), através de valores booleanos ( True ou False ). Após criado esse arquivo, é necessário salvá-lo novamente, dessa vez com a extensão.pyc, que será o arquivo de sua compilação. Há ainda a necessidade da criação de mais um arquivo na mesma pasta, que terá o nome de init.py. O exemplo encontra-se abaixo: from AdditionSpreadsheet import AdditionSpreadsheet def widgetname(): return Addition of two numbers def registerwidget(reg, basicmodules, basicwidgets): reg.add_module(additionspreadsheet) reg.add_input_port(additionspreadsheet,"location",basicwidgets.celllocation) reg.add_input_port(additionspreadsheet,"parcela1",basicmodules.integer) reg.add_input_port(additionspreadsheet,"parcela2",basicmodules.integer) A importação necessária para esse arquivo é da forma from nomearquivo import nomeclasse, em que nomearquivo representa o nome do arquivo que foi criado para o módulo, e nomeclasse é o nome da classe feita nesse arquivo, que deriva da classe SpreadsheetCell. A função widgetname() pode ser definida ou não; ela retorna a especificação do módulo, ou seja, o que ele faz (cria uma documentação do módulo). Já a função registerwidget é obrigatória, definindo a adição do módulo dentro do VisTrails, assim como de suas portas de entrada e saída, da mesma forma que é feito no arquivo

basic_modules.py, já comentado anteriormente. Após a criação, não se pode esquecer-se de criar o mesmo arquivo com a extensão.pyc, ou seja, o arquivo de sua compilação. Depois de feitos todos esses passos, o módulo é adicionado ao VisTrails e já pode ser usado. Abaixo, as Figuras 1 e 2 ilustram o módulo dado como exemplo dentro do programa. Figura 1. A visualização do módulo e de suas entradas (inteiros) pelo VisTrails Figura 2. A visualização, no Spreadsheet, do resultado obtido

Usando VTK Juntamente com o VisTrails, está embutida uma ferramenta de visualização que é bastante eficiente e muito usada: o VTK. Ele é a melhor maneira de se visualizar os resultados no Spreadsheet, já que permite a visualização em uma, duas ou três dimensões. Esse pacote é o utilizado pelo programa para fazer as animações, no Spreadsheet, em 3D. Peguemos o módulo Soma, já mostrado inicialmente, que implementa a adição entre dois números e apresenta o resultado, ou como inteiro (porta soma ), ou como string (porta somacomostring ). Para montar o workflow que mostrará no Spreadsheet o resultado da soma, através do VTK, são necessários os seguintes módulos: vtktextactor: esse módulo é o responsável por guardar a string que aparecerá na visualização; é necessário, assim, habilitar a porta SetInput, que é aquela que recebe a string desejada; para isso, deve-se clicar na seta localizada no canto superior direito do módulo vtktextactor e depois em Edit Configuration ; abrirá uma janela com várias portas de entrada e saída; deve-se localizar a porta de entrada SetInput e habilitá-la; a entrada para essa porta será ativada no módulo na forma de uma círculo, podendo esta ser utilizada; vtktextproperty: para formatar a string colocada no vtktextactor, usa-se esse módulo (ele não é obrigatório); por ele, pode-se escolher diversas características, como fonte, tamanho, cor da letra, sombra, alinhamento (justificado, à esquerda ou à direita), entre outros; sua saída deve ser ligado ao vtktextactor; vtkrenderer: o módulo vtktextactor deve ser ligado a esse módulo; ele é responsável pela renderização, ou seja, ele que cria a visualização em si, capturando as imagens; por ele podem ser escolhidas algumas características da parte visual, como a cor do fundo; VTKCell: esse módulo pertence ao VisTrails; ele é que transmite a visualização, do vtkrenderer, para as células do Spreadsheet; portanto, ele deve estar sempre presente ao final do workflow. Após feita a ligação entre esses módulos (Figura 3), a parte da visualização já está determinada. A partir daí, pode-se ligar qualquer string ao vtktextactor que ela aparecerá no Spreadsheet (Figura 4). No caso do módulo Soma comentado acima, a porta somacomostring deve ser ligada à porta SetInput.

Figura 3. O workflow acima promove a visualização do resultado da soma entre dois números inteiros (nesse caso, os valores são 3 e 8); em destaque, encontra-se algumas características escolhidas para a string pelo módulo vtktextproperty (negrito, fonte Arial, cor da fonte, sombra e tamanho 100 da fonte). Figura 4. A visualização do workflow é apresentada no Spreadsheet com as características definidas pelo usuário.

Há a possibilidade de trocar o módulo vtktextactor pelo vtktextactor3d. Esse módulo capta a string para a visualização da mesma maneira que o primeiro, porém com características de três dimensões. Dessa forma, o usuário pode interagir com a string, movimentando-a pelas três dimensões, assim como pode fazer um zoom nela (Figura 5). Figura 5. Substituindo-se o vtktextactor pelo vtktextactor3d, o usuário pode interagir com o resultado, promovendo alterações na sua posição e, assim, permitindo a visualização em três dimensões. Após ficar movimentando a posição de um determinado resultado, caso o usuário queria salvar essa posição, basta clicar na célula da visualização e depois em Save Camera, que se encontra acima das células no Spreadsheet. Com isso, uma nova versão do workflow será criada com um novo módulo ligado ao vtkrenderer, o vtkcamera, que salva a posição através de três métodos: SetPosition, SetFocalPoint e SetViewUp. Usando o Parameter Exploration O VisTrails possui um recurso muito interessante chamado de Parameter Exploration. Ele é extremamente útil quando se quer carregar um determinado workflow com valores diversos para seus parâmetros, a fim de comparação. Consideremos como exemplo o módulo AdditionSpreadsheet, o qual foi anteriormente mostrado(a Figura 6 ilustra um exemplo de workflow). Ele possui dois parâmetros de entrada: parcela1 e parcela2. Dentro da janela do Pipeline, pode-se determinar o valor de cada um deles, que serão, dessa forma, valores fixos. Caso queiramos executar diversos valores, sem

ficarmos presos a somente um, podemos usar o Parameter Exploration. Nele, o usuário especifica o valor inicial e o valor final de cada parâmetro, e essa ferramenta irá executar o workflow para cada valor que esteja no intervalo determinado. Além disso, pode-se escolher a forma como isso será apresentado no Spreadsheet; os resultados referentes a cada valor podem ser apresentados em colunas ou linhas, por exemplo, e, caso haja mais de um módulo no workflow que gere uma visualização, pode-se escolher a ordem em que eles irão aparecer no Spreadsheet. Esse último recurso é apresentado pela ferramenta Spreadsheet Virtual Cell, a qual fica no canto inferior direito da janela do Parameter Exploration. Para que a faixa de valores de um parâmetro seja determinada, é necessário encontrálo no canto direito da tela e arrastá-lo para o centro da janela (Figura 7). Quando estiver tudo pronto, basta apertar o botão Execute, e o workflow será executado para cada valor de parâmetro (Figura 8). Figura 6. Exemplo de workflow para o uso do Parameter Exploration; as entradas são dois números inteiros, e há duas saídas: o resultado da soma entre os números (módulo AdditionSpreadsheet), e a indicação se esse resultado é um inteiro par ou ímpar (módulo OddAndEven).

Figura 7. Na janela do Parameter Exploration, escolhe-se, arrastando os parâmetros para o centro da tela, os seus valores; nesse caso, os valores dos dois números vão de 0 a 2; a representação escolhida foi a coluna, e o resultado do módulo AdditionSpreadsheet aparecerá antes do OddAndEven, o que pode ser visto através do Spreadsheet Virtual Cell (canto inferior direito). Figura 8. A visualização dos resultados no Spreadsheet

Dentro do Spreadsheet também é gerado um recurso muito útil, que é uma interação entre ele e o Builder, o componente que cria e mantém os pipelines. Após criar a visualização dos resultados dos parâmetros, pode-se gerar novas versões do workflow específicas para cada um deles. Para que isso seja feito, deve-se clicar, dentro do Spreadsheet, em View, e depois em Editing Mode. Assim, aparecerão cinco botões para cada célula de visualização: Copy, Move, Create Analogy, Apply Analogy e Create Version (Figura 9); os dois primeiros servem simplesmente para passar a visualização de um resultado para outras células do Spreadsheet (não provocam modificações no Builder); os botões Create Analogy e Apply Analogy servem para fazer analogias entre duas versões do workflow; o botão Create Version só aparece quando os parâmetros são gerados pelo Parameter Exploration: apertando-o, gera-se uma nova versão do workflow já existente, porém com os parâmetros determinados, parâmetros estes que geraram a visualização na qual o botão foi apertado (Figura 10). Figura 9. Dentro do Editing Mode, pode-se visualizar os botões que geram a interação entre o Spreadsheet e o Builder.

Figura 10. Quando se aperta o botão Create Version da coluna C, por exemplo, é gerada uma nova versão do workflow com os parâmetros (os números inteiros) determinados; nesse caso, a coluna C havia sido gerada pelos inteiros 1 e 1. A faixa de valores de um determinado parâmetro pode ser definida de três maneiras diferentes: Linear Interpolation, List ou User-defined Function. Na primeira maneira, o usuário determina um valor inicial e um valor final para o parâmetro e, de acordo com o número de linhas, colunas, abas ou etapas de tempo escolhido (esta última será melhor discutida adiante), o Parameter Exploration faz um interpolação dos valores; por exemplo, se o valor inicial determinado para um dado parâmetro foi 0, e seu valor final foi 6, e caso o usuário tenha escolhido 3 colunas para a apresentação no Spreadsheet, serão gerados os resultados desse workflow para os valores 0, 3 e 6 do parâmetro (são três valores entre 0 e 6, interpolados linearmente). Caso o usuário escolha List, ele deve determinar uma lista de valores fixos que serão usados no Parameter Exploration. Nesse caso, não se pode esquecer que o número de valores colocados dentro da lista deve ser igual ao número das formas de apresentação; assim, se o usuário define a lista *1,3,4,7+ para um parâmetro qualquer, a quantidade de resultados gerados deve ser igual a 4 (devem ser escolhidas 4 colunas, por exemplo). Quando se escolhe User-defined Function, o usuário pode determinar uma função para a geração dos valores, onde a variável dessa função será, obrigatoriamente, o número de resultados que se deseja; a função é chamada de value(i), e pode-se determinar o que ela irá retornar; dessa forma, se, para essa função, o usuário escreve return i*2, tendo ele escolhido apresentar os seus resultados em 3 linhas, os valores do parâmetro serão 0, 2 e 4 (i começa com o valor 0). Um recurso muito interessante que pode ser gerado através do Parameter Exploration é a criação de pequenas animações. A Figura 11 mostra um exemplo de workflow que utiliza

VTK; ele simplesmente mostra a visualização, no Spreadsheet, do valor de um inteiro; usando o Parameter Exploration, determina-se 10 valores para esse inteiro (de 0 a 9); escolhe-se, como forma de apresentação dos resultados, 10 etapas de tempo (Figura 12); com isso, é gerada no Spreadsheet uma pequena animação, que ficará passando os valores de 0 a 9 (Figura 13). Para que a animação seja ativada, é necessário clicar na célula de visualização e, sem seguida, clicar no botão Play the history. Figura 11. Um exemplo de workflow Figura 12. Para o workflow da Figura 11, foi escolhido, no Parameter Exploration, User-defined Function, em que a função retorna a própria variável; logo, como foram escolhidas 10 etapas de tempo, o parâmetro value terá valores de 0 a 9.

Figura 13. A animação é gerada no Spreadsheet e é ativada apertando-se o botão Play the history ; a figura acima é uma ilustração da animação em cada etapa do tempo.