TerraPHP: Extensão PHP da Biblioteca TerraLib 1. Introdução A
Transcrição
TerraPHP: Extensão PHP da Biblioteca TerraLib 1. Introdução A
TerraPHP: Extensão PHP da Biblioteca TerraLib TERRALIB DEVELOPMENT TEAM Image Processing Division, National Institute for Space Research (INPE), São José dos Campos, Brazil gribeiro(at)dpi.inpe.br Resumo. O TerraPHP é uma extensão da linguagem PHP, construída no topo da biblioteca TerraLib, para facilitar o desenvolvimento de aplicativos Web de visualização e consulta a bancos de dados geográficos. Este relatório apresenta as funcionalidades disponíveis nesta extensão e exemplos de como construir tais aplicações em PHP. Também é mostrado como instalar e configurar o ambiente do TerraPHP nos sistemas operacionais Linux e Windows. 1. Introdução A World Wide Web [01], abreviadamente Web, se tornou uma das mídias mais importantes e preferidas para disseminação de informações. Ela evoluiu de simples páginas com conteúdo estático para páginas com conteúdos dinâmicos, extraídos, principalmente, de Sistemas Gerenciadores de Bancos de Dados (SGBDs) [02]. Para atender à necessidade de construção destas páginas (com conteúdo dinâmico), diversas tecnologias emergiram no final da década passada e, entre elas, pode-se citar: Common Gateway Interface (CGI) [03], Active Server Pages (ASP) [04], Java Server Pages (JSP) [05] e Hypertext Preprocessor (PHP) [06]. Nesta década, a demanda pela disseminação de dados geográficos, tem motivado os principais fornecedores de Sistemas de Informação Geográficas (SIG) [07] a investirem em ferramentas para construção de aplicações que forneçam acesso a esses tipos de dados via Web. A forma mais comum de publicação de dados geográficos neste tipo de mídia é através de mapas em formato de imagem PNG [08] ou JPEG [09]. Existem dois tipos principais de aplicações que utilizam esta forma de disseminação: • Aplicações dedicadas: onde uma aplicação específica é desenvolvida com alguma tecnologia que permita a construção de mapas sob demanda. Neste tipo de aplicação os usuários podem interagir realizando operações de zoom e apontamento sobre a imagem dos mapas embutidos nas páginas exibidas pelos navegadores Web. • Servidores de mapas: são aplicações servidoras de informações geográficas que possuem uma interface bem definida para que aplicações clientes possam solicitar recursos (dados geográficos). O Open GIS fornece especificações para essa classe de aplicação, entre elas, as especificações WMS [10] e WFS [11]. Entre as tecnologias de software livre para desenvolvimento de aplicações Web tradicionais, o PHP ocupa uma posição de destaque. Por se tratar de uma linguagem simples e extensível, o número de desenvolvedores adeptos tem se tornado cada vez maior. Com o objetivo de difundir o uso de geotecnologias, nós desenvolvemos uma extensão para o PHP, chamada TerraPHP. Esta extensão é baseada na biblioteca TerraLib [12] e acrescenta funcionalidades básicas de construção de aplicativos geográficos ao PHP. O presente relatório está organizado da seguinte forma: a Seção 2 apresenta a configuração e instalação da extensão em ambiente Linux; a Seção 3 apresenta as funcionalidades disponíveis do TerraPHP; e a Seção 4 mostra como construir aplicações utilizando a extensão. 2. Instalação e Configuração do TerraPHP no Linux Nesta seção é apresentado como instalar e configurar o ambiente de desenvolvimento no sistema Linux (Sistemas RedHat, Mandrake e Conectiva). 2.1 Bibliotecas Auxiliares Para compilar a extensão TerraPHP serão necessárias as seguintes bibliotecas: • zlib versão 1.2.2, disponível em: http://www.gzip.org/zlib. • libpng versão 1.2.8 disponível em: http://www.libpng.org/pub/png. • IJG JPEG library versão 6 disponível em: http://www.ijg.org. • libgd versão 2.0.33 disponível em: http://www.boutell.com/gd. • lib FreeType versão 2.1.9 disponível em: http://sourceforge.net/projects/freetype. As distribuições Linux já acompanham estas bibliotecas e as versões citadas, não são obrigatórias, porém, correspondem às utilizadas em nossos experimentos. 2.2 Servidor de Banco de Dados MySQL Instalar a versão 4.1.12 disponível em http://www.mysql.com: • Criação do usuário e grupo mysql (caso não existam no sistema): groupadd mysql useradd -g -c -d -s • mysql "MySQL Server" /usr/local/mysql /bin/bash mysql Instalação e setup inicial do mysql: cd /usr/local tar xzf /tmp/soft/mysql-standard-4.1.12-pc-linux-i686.tar.gz ln -s mysql-standard-4.1.12-pc-linux-i686 mysql cd mysql scripts/mysql_install_db chown -R root . chown -R mysql data chgrp -R mysql . • Inicialização no boot (arquivo mysql disponível em http://www.terralib.org/terraphp): cp mysql /etc/init.d chown root /etc/init.d/mysql chmod 744 /etc/init.d/mysql chkconfig --level 2345 mysql on service mysql start • Senha de root do MySQL: /usr/local/mysql/bin/mysqladmin -u root password new-password 2.3 Biblioteca TerraLib e TerraView Os códigos fonte da biblioteca TerraLib e do aplicativo TerraView encontram-se disponíveis para download em http://www.terralib.org ou por meio do servidor CVS. 1. Criar um diretório chamado terralib_cvs dentro do diretório “/root” e alterar o diretório corrente: cd /root mkdir terralib_cvs cd terralib_cvs 2. Obter os arquivos fontes do TerraView e TerraLib a partir do CVS: • Logar no servidor CVS: cvs –d :pserver:[email protected]:/home/terralib login • Baixar o diretório src: cvs • -d :pserver:[email protected]:/home/terralib co src Baixar o diretório terralibx: cvs -d :pserver:[email protected]:/home/terralib co terralibx • Baixar o diretório aplicativos: cvs -d :pserver:[email protected]:/home/terralib co aplicativos • Baixar o diretório extensions: cvs -d :pserver:[email protected]:/home/terralib co extensions 3. Compilar a biblioteca TerraLib: • Entrar no diretório terralibx/shapelib e executar make; • Entrar no diretório terralibx/tiff e executar make; • Entrar no diretório terralibx/terralib e executar make; • Entrar no diretório terralibx/stat e executar make; • Entrar no diretório terralibx/image_processing e executar make; 4. Compilar o aplicativo TerraView: • Entrar no diretório aplicativos/terraView/linux e executar make. 5. Ir para o diretório /usr/local/lib e criar links simbólicos para as bibliotecas geradas na etapa anterior: cd /usr/local/lib ln –s /root/terralib_cvs/terralibx/terralib/*so* . ln –s /root/terralib_cvs/terralibx/tiff/*so* . ln –s /root/terralib_cvs/terralibx/shapelib/*so* . ln –s /root/terralib_cvs/terralibx/stat/*so* . ln –s /root/terralib_cvs/terralibx/image_processing/*so* . 6. Criar o diretório "/usr/local/include/terralib", alterar o diretório atual para ele e então criar links simbólicos para os arquivos de cabeçalho da TerraLib: ln –s /root/terralib_cvs/src/terralib/kernel/*.h . ln -s /root/terralib_cvs/src/terralib/functions/*.h . ln -s /root/terralib_cvs/src/terralib/functions/stat/*.h . ln -s /root/terralib_cvs/src/terralib/application/*.h . ln -s /root/terralib_cvs/src/terralib/application/qt/*.h . ln -s /root/terralib_cvs/src/terralib/drivers/MySQL/*.h . ln -s /root/terralib_cvs/extensions/terramanager/src/*.h . 2.4 Servidor HTTP Apache Instalar a versão 1.3.33 disponível em http://www.apache.org/: 1. Criação do usuário e grupo apache (caso não existam no sistema): groupadd apache useradd -g apache -c "Apache Server" -d /usr/local/apache -s /bin/false apache 2. Compilação e instalação: cd /tmp/soft tar xzf apache_1.3.31.tar.gz cd apache_1.3.31 ./configure --enable-module=so make make install 3. Inicialização no boot (arquivo httpd em anexo): cp httpd /etc/init.d chown root /etc/init.d/httpd chmod 744 /etc/init.d/httpd chkconfig --level 2345 httpd on 4. Configuração do apache – editar o arquivo /usr/local/apache/conf/httpd.conf: • Para o apache interpretar a extensão php, coloque em httpd.conf, logo após a linha AddType application/x-tar .tgz: AddType application/x-httpd-php • .php Para o apache interpretar index.php, coloque em httpd.conf na linha DirectoryIndex index.html: DirectoryIndex index.html index.php 5. NÃO inicializar o serviço httpd por enquanto. 2.5 PHP Descompactar a versão 4.3.11 disponível em http://www.php.net: cd /tmp/soft tar xzf php-4.3.11.tar.gz cd php-4.3.11 2.6 Extensão TerraPHP 1. Entrar no diretório “ext” dentro da raiz de diretórios do PHP e criar o diretório terraweb: cd ext mkdir terraweb cd terraweb 2. Criar links para arquivos da extensão TerraPHP e do TerraManager: ln –s /root/terralib_cvs/extensions/terraphp/src/config.m4 . ln –s /root/terralib_cvs/extensions/terraphp/src/php_terraweb.h . ln -s /root/terralib_cvs/extensions/terramanager/src/terraweb.cpp . ln -s /root/terralib_cvs/extensions/terramanager/src/TeDecoderGDImage .cpp . ln -s /root/terralib_cvs/extensions/terramanager/src/TeGDCanvas.cpp . ln -s /root/terralib_cvs/extensions/terramanager/src/TerraManager.cpp . 3. Criar links para arquivos auxiliares da TerraLib necessários ao TerraPHP: ln –s /root/terralib_cvs/src/terralib/application/TeApplicationUtils. cpp . ln –s /root/terralib_cvs/src/terralib/application/TeDatabaseUtils.cpp . ln –s /root/terralib_cvs/src/terralib/application/TeColorUtils.cpp . ln –s /root/terralib_cvs/src/terralib/application/TeThemeApplication. cpp . ln –s /root/terralib_cvs/src/terralib/functions/TeLayerFunctions.cpp . ln –s /root/terralib_cvs/src/terralib/drivers/MySQL/TeMySQL.cpp . A última linha acima, inclui o driver a ser utilizado na extensão TerraPHP: no caso MySQL. Caso deseje-se utilizar um outro, como o driver PostgreSQL, será necessário alterar o arquivo config.m4. Para isso, acrescente os nomes dos arquivos fontes do driver PostgreSQL (TePostgreSQL.cpp, TePGInterface.cpp, TePGUtils.cpp, TePostGIS.cpp) neste arquivo, logo após o arquivo TeMySQL.cpp. Além disso, no arquivo TerraManager.cpp, será preciso habilitar o flag do driver PostgreSQL (#define HAS_POSTGRESQL 0 para #define HAS_POSTGRESQL 1). 4. Compilação e instalação do PHP: cd ../.. ./buildconf --force ./configure --with-apxs=/usr/local/apache/bin/apxs --enablemagic-quotes --enable-track-vars --enable-calendar --withgettext --with-mysql=/usr/local/mysql --with-xml --with-gd -with-freetype-dir=/usr --enable-gd-native-ttf --enable-gdimgstrttf --with-zlib --enable-ftp --enable-debugger --enableinline-optimization --enable-memory-limit --enable-posix -enable-session --without-kerberos --enable-trans-sid --enablesafe-mode --with-exec-dir=/usr/bin --with-terraweb make make install cp php.ini-dist /usr/local/lib/php.ini service httpd start Para habilitar o driver PostgreSQL, será necessário acrescentar o flag --withpgsql=local_das_bibliotecas_postgresql 3. TerraPHP O PHP (Hypertext Preprocessor) é uma linguagem de script bastante utilizada no desenvolvimento de páginas Web dinâmicas. Geralmente, os códigos PHP (chamados de scripts) são delimitados pelas tags <?php e ?>, sendo embutidos nas páginas HTML. O código entre estas tags é processado no servidor (como por exemplo, Apache) antes da página ser enviada ao cliente (navegador ou webbrowser). O código fonte de PHP é portável, aberto e escrito em linguagem C. No seu núcleo, são encontradas as funcionalidades básicas de toda linguagem de programação: estruturas de controle, laços, classes, operações aritméticas, operações relacionais e operações lógicas entre outras. As funcionalidades específicas, como manipulação de documentos (XML, PDF e etc) e comunicação com bancos de dados (PostgreSQL, Oracle e etc), são fornecidas através de extensões. A arquitetura de PHP possibilita a criação de extensões que podem ser utilizadas dentro da linguagem. O TerraPHP é uma extensão que adiciona facilidades para consulta e visualização de dados geográficos. Estas facilidades estão disponíveis na forma de uma classe interna chamada TerraWeb. A forma de implementação (classe interna) utilizada permite o uso de um estilo de programação orientado a objeto, como o mostrado no fragmento de código abaixo: 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 <? $t = TerraWeb(); if(!$t->connect("localhost", "nome_usuario", "senha", "nome_banco", 3306, 1)) { echo("ERRO!!!"); echo($t->errorMessage()); exit(); } else { echo("A conexao foi um sucesso!"); } ?> A classe TerraWeb fornece métodos para estabelecimento de uma conexão a um servidor de bancos de dados, exploração do conteúdo do banco e fornece um canvas (abstração de uma área para desenho) que pode ser utilizado para visualizar a componente espacial dos objetos geográficos do banco de dados (Figura 1). O desenho sobre o canvas pode ser materializado através de imagens no formato PNG ou JPEG. Figura 1 - TerraPHP Antes de detalhar os métodos disponíveis na classe TerraWeb é preciso falar de três conceitos empregados no projeto da extensão: vista corrente, temas ativos e representação corrente. A vista corrente define a projeção em que todos os temas e objetos do banco de dados serão visualizados. Ela define também os temas que estarão disponíveis para visualização e consulta. Qualquer método que receba valores de coordenadas como parâmetro (plotPoint, plotText, plotBox entre outros) assumirá que as coordenadas encontram-se na mesma projeção da vista corrente. Para começar a desenhar um tema ou objeto de um tema, é necessário ter uma vista corrente ativada (setCurrentView). Os temas ativos são utilizados nas operações de localização de objetos e desenho no canvas. Pode-se ter no máximo dois temas ativos por vez: • tema corrente: define o tema no qual certas operações deverão ser realizadas. Somente os temas correntes podem ser desenhados sobre o canvas. • tema de referência: geralmente utilizado como referência para localização de objetos relacionados com o tema corrente. Por exemplo, se no tema corrente temos objetos que representam queimadas (pontos) e no tema de referência temos objetos que representam municípios (polígonos), poderíamos realizar a seguinte consulta espacial: “localizar o município que contém um determinado ponto de queimada”. Exemplos práticos de uso desses dois tipos de temas serão mostrados na próxima seção. O último conceito importante é o de representação corrente. Para cada um dos tipos de tema (corrente e referência) é possível indicar quais as respectivas representações geométricas ativas. Estas representações afetam as operações espaciais e o desenho de objetos selecionados. Figura 2 – Métodos da classe TerraWeb A Figura 2 mostra todos os métodos da classe TerraWeb. Estes métodos podem ser agrupados, segundo suas funcionalidades, em: 1. Método de checagem de erro: a. errorMessage: retorna uma mensagem com o último erro ocorrido; Sintaxe: errorMessage() : string 2. Método de estabelecimento de conexão ao servidor de bancos de dados: a. connect: recebe as informações necessárias para abertura de uma conexão a um servidor de bancos de dados. Sintaxe1: connect(host : string, user : string, password : string, database : string[, port : int[, dbType : int]]) : bool onde o valor do parâmetro dbType pode ser: 1 para MySQL, 2 para PostgreSQL, 3 para PostGIS, 4 para Access, 5 para Oracle, 6 para SqlServer, 7 para Oracle Spatial. 3. Métodos para exploração do conteúdo bancos de dados geográficos: a. getViews: retorna a lista de vistas armazenadas em um banco de dados. Sintaxe: getviews(user : string) : array 1 Os parâmetros entre colchetes são opcionais. b. setCurrentView: coloca uma determinada vista como a vista corrente. Sintaxe: setCurrentView(view : string) : bool c. getCurrentView: retorna o nome da vista colocada com corrente. Sintaxe: getcurrentview() : string d. getCurrentViewBox: retorna um vetor de quatro elementos float contendo as coordenadas do retângulo envolvente dos objetos da vista corrente (x1, y1, x2 e y2 respectivamente). Os valores das coordenadas encontram-se no sistema de projeção indicado pela vista corrente. Sintaxe: getCurrentViewBox() : array e. setTheme: coloca um tema como tema corrente ou tema de referência. Sintaxe: setTheme(theme : string[, themeType : int]) : bool O parâmetro themeType2 pode ser usado para especificar o tipo do tema: “0” indica que o tema é corrente e “1” que o tema é de referência. f. getTheme: retorna o nome do tema corrente ou de referência. Sintaxe: getTheme([themeType : int]) : string O parâmetro themeType pode ser usado para especificar o tipo do tema: “0” indica que é para retornar o nome do tema corrente e “1” que o do tema de referência. g. getThemeRepresentation: retorna as representações ativas do tema corrente ou do tema de referência. Sintaxe: getThemeRepresentation([themeType : int]) : int h. getThemes: retorna um vetor com o nome dos temas da vista corrente. Sintaxe: getThemes() : array i. setActiveThemeRepresentation: indica qual será a representação geométrica ativa do tema corrente ou do tema de referência. Sintaxe: setActiveThemeRepresentation(repres : int[, themeType : int]) : bool Os valores e significados do parâmetro “repres” são: 1 Polígonos 2 Linhas 4 Pontos 128 Texto 256 Células 512 Raster 2 Em todos os métodos onde themeType é opcional o valor padrão é 0, ou seja, o método se refere ao tema corrente. j. getActiveThemeRepresentation: retorna qual é a representação geométrica ativa do tema corrente ou do tema de referência. Sintaxe: getActiveThemeRepresentation(themeType : int) : int k. getThemeBox: retorna um vetor de quatro elementos float contendo as coordenadas do retângulo envolvente dos objetos do tema corrente ou de referência (x1, y1, x2 e y2 respectivamente). Os valores das coordenadas encontram-se no sistema de projeção indicado pela vista corrente. Sintaxe: getThemeBox([themeType : int[, restriction : string]]) : array Caso uma restrição seja aplicada ao tema, retorna o retângulo envolvente dos objetos do tema que satisfazem a restrição. 4. Métodos para manipulação do canvas: a. setWorld: ajusta o tamanho (largura e altura) do canvas a ser desenhado e a área de interesse de visualização. As coordenadas desta área devem estar no sistema de projeção da vista corrente. Sintaxe: setWorld(x1 : float, y1 : float, x2 : float, y2 : float, width : int, height : int) : array b. pixelSize: retorna a espessura de um pixel na unidade de projeção da vista corrente. Sintaxe: pixelSize() : float c. getPng: retorna uma imagem no formato PNG das representações vetoriais desenhadas sobre o canvas. Sintaxe: getPng() : string d. getJpg: retorna uma imagem no formato JPEG das representações raster desenhadas sobre o canvas. Sintaxe: getJpg([quality : int]) : string e. getLegendPng: retorna uma imagem no formato PNG da legenda desenhada com o método plotLegend. Sintaxe: getLegendPng() : string f. setDefaultVisual: ajusta o visual de uma determinada representação geométrica a ser desenhada. Os seguintes métodos utilizam este visual: plotSelectedObject, plotPoint, plotBox, plotTex, plotBufferZone e plotLegend. Sintaxe: setDefaultVisual(rep : int, red : int, green : int, blue : int, style : int, width : int, fontName : string[, rcontour : int, gcontour : int, bcontour : int, stylecontour : int, widthcontour : int]) : bool Os parâmetros: rcontour, gcontour, bcontour, stylecontour e widthcontour devem ser informados no caso de ajuste do visual de polígonos. O parâmetro fontName pode ser o nome e caminho completo de uma fonte TrueType. Neste caso o parâmetro width indica o tamanho da fonte. Caso o nome da fonte não seja especificado (usa-se string vazia: “”) o parâmetro width indica o estilo de fonte própria a ser utilizado e, neste caso, pode variar de 0 a 4. g. plotPoint: desenha um ponto sobre o canvas. As coordenadas do ponto devem estar no sistema de projeção da vista corrente. Sintaxe: plotPoint(x : float, y : float) : bool h. plotBox: desenha um retângulo sobre o canvas. As coordenadas do retângulo devem estar no sistema de projeção da vista corrente. Sintaxe: plotBox(x1 : float, y1 : float, x2 : float, y2 : float[, fill : int]) : bool O parâmetro fill indica se o retângulo será preenchido (1) ou vazado (0). No primeiro caso o visual de polígonos será utilizado e no segundo, o visual de linhas. i. plotLine: desenha uma linha sobre o canvas, informada por uma matriz bidimensional contendo os pares de coordenadas de cada ponto pertencente à linha. As coordenadas devem estar no sistema de projeção da vista corrente. Sintaxe: plotLine(linePoints : array) : bool j. plotPolygon: desenha um polígono sobre o canvas. O anel externo deve ser informado por uma matriz bidimensional contendo os pares de coordenadas de cada ponto pertencente à fronteira no sistema de projeção da vista corrente. Sintaxe: plotPolygon(polygonPoints : array) : bool k. plotVector: desenha o conteúdo vetorial do tema corrente no canvas. As possiblidades de desenho são: desenhar todo o tema corrente; desenhar apenas alguns objetos do tema corrente que satisfaçam alguma restrição; desenhar os objetos de um tema agrupados por alguma função de agrupamento (passos iguais, quantil, valor único e etc) com algum tom de cores. Sintaxe: plotVector([restriction : string[, groupAttName : string, groupAttNorm : string, numSlices : int, groupType : int, ramp : array, prec : int][, stdDev : double]]) : array O parâmetro restriction indica se algum filtro será aplicado nos objetos do tema corrente. Os demais parâmetros indicam se o desenho do tema deve satisfazer algum agrupamento. Neste caso o parâmetro groupAttName indica o nome do atributo utilizado para agrupar os objetos em classes, o atributo groupAttNorm se especificado indica o atributo normalizador, numSlices define o número de classes do agrupamento, ramp é um vetor que contem uma lista de tons de cores a serem utilizadas no desenho do agrupamento e prec indica o número de casas decimais utilizadas no agrupamento. O parâmetro stdDev indica o desviuo padrão utilizado no caso de agrupamentos deste tipo. O retorno dessa função é uma matriz com as informações de legenda do tema desenhado. l. plotRaster: desenha o conteúdo matricial (raster) do tema corrente. Sintaxe: plotRaster() : bool m. plotSelectedObjects: desenha no canvas um conjunto de objetos indicados por uma lista de identificadores (object_id). Somente a representação ativa (do tema corrente ou do tema de referência) serão desenhados. Sintaxe: plotselectedobjects(objArray : array[, themeType : int]) : bool n. plotBufferZone: desenha um mapa de distância ao redor do objeto indicado. Sintaxe: plotbufferzone(objId : string, dist : float[, themeType : int]) : bool o. plotText: desenha um texto sobre o canvas na posição indicada. Pode-se utilizar uma fonte TrueType ou fontes nativas da GD. Para isto é necessário ajustar as configurações do visual de texto através do método setDefaultVisual. Sintaxe: plottext(x : float, y : float, text : string, angle : float, alignh : float, alignv : float) : bool p. plotLegend: desenha uma legenda em um canvas auxiliar. Essa área será automaticamente apagada quando uma nova chamada a este método for realizada. Sintaxe: plotlegend(objArray : array, width : int) : bool q. savePlot: salva no disco um arquivo PNG com o conteúdo vetorial do canvas. Sintaxe: savePlot(fileName : string) : bool r. saveImage: salva em disco um arquivo JPEG com o conteúdo matricial (raster) do canvas. Sintaxe: saveImage(fileName : string[, quality : int]) : bool s. saveLegend: salva em um arquivo PNG em disco o desenho de objetos matriciais (raster) sobre o canvas. Sintaxe: saveLegend(fileName : string) : bool t. cleanCanvas: limpa a área do canvas. É necessário ajustar o tamanho e a área de visualização antes de começar a realizar novos desenhos. Sintaxe: cleanCanvas() : bool 5. Métodos para localização de objetos: a. locateObject: consulta por apontamento. Retorna o identificador do objeto que contém um determinado ponto. Sintaxe: locateObject(x : float, y : float[, tol : float[, themeType : int]]) : array O vetor de retorno é associativo e possui duas entradas: object_id e geom_id. b. locateObjectsInBox: localiza os objetos do tema corrente ou de referência que interajam com um retângulo segundo um relacionamento topológico. Sintaxe: locateObjectsInBox(x1 : float, y1 : float, x2 : float, y2 : float[, relation : int[, themeType : int]]) : array Esse método retorna um vetor contendo os identificadores de objetos que satisfazem o relacionamento (relation) com o retângulo informado. As coordenadas do retângulo devem estar no mesmo sistema de coordenadas da vista corrente. Os valores e significados do parâmetro “relation” são: 1 Disjunto 32 Contém 2 Toca 64 Intercepta3 4 Cruza 128 Igual 8 Dentro 256 Cobre 16 Sobrepõem 512 Coberto Por c. locateObjects: dado o identificador de um objeto, retorna a lista de objetos (identificadores) que satisfaçam um certo relacionamento topológico (toca, cruza, sobrepõe, dentro, contém, disjunto) no tema corrente ou de referência. Sintaxe: locateObjects(objid : string, relation : int, themeType : int) : array d. locateObjectsInArray: dado um vetor de identificadores de objetos, retorna a lista de objetos (identificadores) que satisfaçam um certo relacionamento topológico (toca, cruza, sobrepõe, dentro, contém, disjunto) no tema corrente ou de referência. Sintaxe: locateObjectsInArray(objIdsIn : array, relation : int, themeType : int) : array e. locateObjectsUsingRefTheme: dado um identificador de um objeto do tema corrente, retorna a lista de objetos (identificadores) do tema de referência que satisfaçam um certo relacionamento topológico (toca, cruza, sobrepõe, dentro, contém, disjunto) com ele. Sintaxe: locateObjectsUsingRefTheme(objid : string, relation : int) : array f. locateObjectsUsingRefTheme: dado um identificador de um objeto do tema corrente, retorna a lista de objetos (identificadores) do tema de referência que satisfaçam um certo relacionamento topológico (toca, cruza, sobrepõe, dentro, contém, disjunto) com ele. Sintaxe: locateObjectsUsingRefTheme(objid : string, relation : int) : array g. locateObjectInArraysUsingRefTheme: dado uma lista de identificadores de objetos do tema corrente, retorna a lista de objetos (identificadores) do tema de referência que satisfaçam um certo relacionamento topológico (toca, cruza, sobrepõe, dentro, contém, disjunto) com eles. Sintaxe: locateObjectInArraysUsingRefTheme(objIdsIn : array, relation : int) : array 6. Métodos para localização de atributos dos objetos: 3 É o relacionamento padrão utilizado caso nenhum outro seja especificado. a. fetchAttributes: retorna a lista de atributos de um dado objeto. Sintaxe: fetchAttributes(objectid : string[, themeType : int]) : array O retorno deste método é um vetor associativo: nome_atributo/valor. Na próxima seção iremos mostrar através de exemplos como utilizar a extensão TerraPHP na construção de aplicações Web. 5. Programando com o TerraPHP Como a extensão foi implementada na forma de uma classe interna, antes de começarmos a utilizar as suas funcionalidades, é necessário instanciar um objeto da classe TerraWeb. Isto pode ser feito da seguinte forma: <? $t = terraweb(); ?> A chamada aos métodos do objeto é realizada utilizando o operador “->”. Quase todos os métodos disponíveis pressupõem que uma conexão esteja estabelecida, antes de serem invocados. O método connect, deverá sempre ser um dos primeiros métodos presentes nas primeiras linhas de um programa que utilize o TerraPHP: <? $t->connect("localhost", "nome_usuario", "senha", "nome_banco", 3306, 1); ?> Como será visto, quase todos os métodos retornam o valor “falso” quando ocorre um erro. No trecho de código do Programa 1, na linha 02 um objeto TerraWeb é instanciado. A seguir, na linha 04, é testado se a conexão com um servidor MySQL (tipo do servidor = 1) é aberta. Caso ocorra algum erro durante a abertura da conexão, como nome de usuário ou senha inválidos, o método connect retornará falso, e neste caso uma mensagem de erro poderá ser obtida através do método errorMessage (linha 07). A conexão com o servidor bem como quaisquer recursos alocados pelo TerraWeb, serão descartados automaticamente ao final do escopo dos objetos. A saída do programa pode ser visto na Figura 3. Programa 1 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 <? $t = terraweb(); if(!$t->connect("localhost", "nome_usuario", "senha", "nome_banco", 3306, 1)) { echo("Nao foi possivel conectar-se ao banco de dados<BR>"); echo($t->errorMessage()); exit(); } else { echo("A conexao foi um sucesso!"); } ?> Figura 3 – Saída do Programa 1 O próximo exemplo, o Programa 3, mostra como obter as vistas armazenadas em um banco de dados. Na linha 11, o método getViews é chamado. Caso as vistas sejam localizadas, a variável views irá conter um vetor com o nome das vistas. Na linha 20, um laço é realizado, imprimindo o nome de cada vista. A Figura 2 mostra o resultado deste trecho de programa. Programa 2 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 <? $t = terraweb(); if(!$t->connect("localhost", "nome_usuario", "senha", "nome_banco", 3306, 1)) { echo("Nao foi possivel conectar-se ao banco de dados<BR>"); echo($t->errorMessage()); exit(); } $views = $t->getviews(“nome_usuario”); if($views == false) { echo("Nao fo possivel recuperar as vistas para o usuário root <BR>"); echo($t->errorMessage()); exit(); } for($j = 0; $j < count($views); ++$j) echo($views[$j] . "<BR>"); ?> Figura 4 – Saída do Programa 2 Para obtermos o retângulo envolvente dos temas contidos em uma dada vista e o nome destes temas, é necessário colocá-la como a vista corrente. O Programa 3 mostra na linha 24, a utilização do método setCurrentView, que coloca a vista informada como a vista corrente. Com uma vista corrente ajustada, podemos solicitar os valores das coordenadas que definem o retângulo envolvente dos temas nesta vista através do método getCurrentViewBox (linhas 31 e 39). Através do método getThemes podemos ter o acesso aos nomes dos temas contidos na vista (linha 42). A Figura 5 mostra a saída deste trecho de programa. Programa 3 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 <? $t = terraweb(); if(!$t->connect("localhost", "nome_usuario", "senha", "nome_banco", 3306, 1)) { echo("Nao foi possivel conectar-se ao banco de dados<BR>"); echo($t->errorMessage()); exit(); } $views = $t->getviews(); if($views == false) { echo("Nao fo possivel recuperar as vistas para o usuário root <BR>"); echo($t->errorMessage()); exit(); } for($j = 0; $j < count($views); ++$j) { echo("==> VISTA: " . $views[$j] . "<BR>"); if($t->setCurrentView($views[$j]) == false) { echo($t->errorMessage() . "<BR>"); exit(); } $box = $t->getcurrentviewbox(); if($box == false) { 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 echo($t->errorMessage() . "<BR>"); exit(); } echo("BOX: X1 = " . $box[0] . " , Y1 = " . $box[1] . ", X2 = ". $box[2] . ", Y2 = " . $box[3] . "<BR>"); $themes = $t->getthemes(); if($themes == false) { echo($t->errorMessage() . "<BR>"); exit(); } for($i = 0; $i < count($themes); ++$i) { echo(" ---Tema: " . $themes[$i] . "<BR>"); } echo("<BR>"); } ?> Figura 5 – Saída do Programa 3 Até aqui, vimos como consultar as informações disponíveis no banco: informações sobre vistas e temas. O Programa 4, mostra como desenhar as informações de um tema matricial (raster) sobre o canvas e então visualizar o resultado deste desenho. Para utilizar o canvas é necessário realizar alguns ajustes com o método setWorld. Na linha 25, as coordenadas do mundo, que definem a área visível, são ajustadas com os valores do retângulo envolvente da vista. Isto significa que qualquer objeto de qualquer tema poderá ser desenhado sobre o canvas. Caso as coordenadas tivessem sido restritas a uma determinada área, apenas os objetos contidos nela serão desenhados. Nesta mesma linha, as dimensões do canvas são informadas: 800 x 600. Estas dimensões informam qual será o tamanho da imagem do desenho do canvas. Para desenharmos um tema, é necessário que este seja colocado com o tema corrente. Na linha 37, um tema é colocado como corrente. O parâmetro “0” indica que o nome do tema fornecido é para ajustar um tema corrente com este nome. Tendo um tema corrente, o método plotRaster desenha o seu conteúdo sobre o canvas (linha 39). Os desenhos da representação matricial ficam disponíveis para visualização no formato de imagem JPEG e podem ser acessados através do método getJpg (linha 48). As linhas 49 e 50 retornam para o navegador (webbrowser) uma página com conteúdo de imagem JPEG. A Figura 6 mostra a saída deste programa. Programa 4 01 02 03 04 05 06 07 08 09 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 <? $t = terraweb(); if(!$t->connect("localhost", "nome_usuario", "senha", "nome_banco", 3306, 1)) { echo("Nao foi possivel conectar-se ao banco de dados<BR>"); echo($t->errorMessage()); exit(); } if($t->setCurrentView("NATIVIDADE") == false) { echo($t->errorMessage() . "<BR>"); exit(); } $box = $t->getcurrentviewbox(); if($box == false) { echo($t->errorMessage() . "<BR>"); exit(); } $t->setWorld($box[0], $box[1], $box[2], $box[3], 800, 600); $themes = $t->getthemes(); if($themes == false) { echo($t->errorMessage() . "<BR>"); exit(); } for($i = 0; $i < count($themes); ++$i) { $t->setTheme($themes[$i], 0); $result = $t->plotraster(); if($result == false) { echo($t->errorMessage() . "<BR>"); exit(); } } $imagemSaida = $t->getjpg(); header ("Content-type: image/jpg"); echo($imagemSaida); ?> Figura 6 – Saída do Programa 4 No diretório examples você poderá encontrar exemplos mais avançados de uso da extensão TerraPHP, como a visualização de mapas vetoriais (pontos, linhas e polígonos), construção de legendas, construção de mapas resultantes de agrupamentos e uso de fontes true type. Referências [01] W3C. A little history of the World Wide Web. Disponível em: <http://www.w3.org/History.html>. Acesso em: Julho, 2005. [02] Date, C. J. Introdução a sistemas de bancos de dados. Rio de Janeiro: Campus, 1990. [03] The Common Gateway Interface. Disponível em: <http://hoohoo.ncsa.uiuc.edu/cgi/overview.html>. Acesso em: Julho, 2005. [04] Homer, A.; et al.; Professional Active Server Pages 3.0. USA: Wrox, 1999. [05] JavaServer Pages technology. Disponível em: <http://java.sun.com/products/jsp/>. Acesso em: Julho, 2005. [06] PHP documentation. Disponível em: <http://www.php.net/docs.php>. Acesso em: Julho, 2005. [07] Câmara, G.; Casanova, M. A.; Hemerly, A. S.; Magalhães, G. C.; Medeiros, C. M. B. Anatomia de sistemas de informação geográfica. Campinas: Unicamp, 1996. [08] A basic introduction to PNG features. Disponível em: <http://www.libpng.org/pub/png/pngintro.html>. Acesso em: Julho, 2005. [09] JPEG. Disponível em: <http://www.w3.org/Graphics/JPEG/>. Acesso em: Julho, 2005. [10] Web Map Service. Disponível em: <http://www.opengeospatial.org/specs/?page=specs>. Acesso em: Julho, 2005. [11] Web Feature Service Implementation Specification. Disponível em: <http://www.opengeospatial.org/specs/?page=specs>. Acesso em: Julho, 2005. [12] Câmara, G.; Souza, R. C. M.; Pedrosa, B. M.; Vinhas, L.; Monteiro, A. M. V.; Paiva, J. A. Paiva; Carvalho, M. T.; Gatass, M. Terralib: technology in support of GIS innovation. In: Workshop Brasileiro de Geoinformática, 2., 2000, São Paulo. Anais... São Paulo: INPE, 2000, p. 126-133.