# I3geo/Instalação
## Instalação
### Download

O I3Geo pode ser obtido no endereço: http://mapas.mma.gov.br/download
No diretório arquivos estão os arquivos compactados da última versão disponível, para Windows e Linux. Na versão Linux, o arquivo zip contém apenas o diretório i3geo, e na versão para Windows o diretório ms4w, que deve ser tratado como explicado nos tópicos seguintes.
O ms4w (veja) é um pacote para Windows que traz o Apache, PHP e Mapserver já instalados, bastando copiar a pasta ms4w para o diretório local (drive c:).

### Requisitos para instalação

O seguinte software é necessário para o correto funcionamento do I3Geo:
* Servidor Apache;
* PHP 5;
* Mapserver;
* PHP Mapscript.
* R + biblioteca spatstat ver. Caso o R não seja instalado, algumas funcionalidades de geração de gráficos e análises de distribuição de pontos, não poderão ser executadas.
No caso da compilação do Mapserver, geralmente realizada em sistemas Linux, deve-se utilizar as opções GEOS, WMS/WFS Client e WMS/WFS Server. Exemplo do retorno do comando mapserv.exe -v de uma instalação padrão:
MapServer version 4.8.3 OUTPUT=GIF OUTPUT=PNG OUTPUT=JPEG OUTPUT=WBMP OUTPUT=PDF OUTPUT=SWF OUTPUT=SVG SUPPORTS=PROJ SUPPORTS=FREETYPE SUPPORTS=WMS_SERVER SUPPO RTS=WMS_CLIENT SUPPORTS=WFS_SERVER SUPPORTS=WFS_CLIENT SUPPORTS=WCS_SERVER SUPPORTS=THREADS SUPPORTS=GEOS INPUT=JPEG INPUT=POSTGIS INPUT=OGR INPUT=GDAL INPUT=SHAPEFILE DEBUG=MSDEBUG
As seguintes extensões devem também ser ativadas no PHP:
* php_mbstring
* php_gd
* php_xmlrpc
* php_xsl

### Instalação padrão

O uso da instalação padrão é recomendado quando não é desejado alterar os arquivos originais do I3Geo, o que simplifica a instalação. No caso de já existir um servidor de internet, ou a estrutura de diretórios da instalação padrão não ser adequada, pode-se optar pela alteração desses arquivos.
Para a instalação padrão no sistema operacional Windows, basta copiar para a raiz do drive C o diretório ms4w e todo seu conteúdo. Se o ms4w já estiver instalado no computador, basta copiar o diretório i3geo para o diretório C:\ms4w\apache\htdocs\. Nesse caso, deve-se também configurar o arquivo c:\ms4w\apache\cgi-bin\php.ini conforme indicado no tópico anterior (diretiva para variáveis globais e extensões).
Para iniciar o I3Geo, ative primeiro o servidor Apache, dando um duplo clique no arquivo c:\ms4w\apache-install.bat. Após esse procedimento e não ocorrendo erros, abra o navegador de Internet e digite no lugar da URL http:\\localhost\i3geo.
No sistema operacional Linux, o software necessário ao funcionamento do I3Geo deve ser instalado a priori no computador. Estando esse software funcionando, crie o diretório /opt/www/html e copie o diretório i3geo, existente no arquivo zip, para esse diretório. Crie também o diretório /var/tmp/ms_tmp, dando direito de escrita e leitura para os grupos necessários a operação do Apache.
O diretório ms_tmp é utilizado pelo Mapserver para o armazenamento de arquivos de desenho do mapa, devendo estar disponível ao servidor web Apache para escrita e leitura. É necessário também editar os arquivos php.ini e httpd.conf, adaptando-os para os novos diretórios. Basicamente, o servidor Apache precisa reconhecer o diretório /opt/www/html como a raiz dos documentos web. Em muitas instalações pode ocorrer do servidor web não reconhecer o diretório ms_tmp como um diretório válido. Nesse caso, uma alternativa é criar um link simbólico dentro do diretório 'html' apontando para o ms_tmp.

### Instalação específica

O I3Geo pode ser instalado em um diretório diferente do indicado no tópico anterior. Nesse caso, são necessárias alterações em alguns arquivos para que o local de instalação seja reconhecido. Essas alterações estão documentadas nos próprios arquivos listados abaixo.
* i3geo/ms_configura.php
* i3geo/aplicmap/geral1.map
* i3geo/aplicmap/geral1windows.map
* i3geo/aplicmapa/geral.htm

### Descrição dos diretórios

O diretório i3geo contém os seguintes sub-diretórios:
* aplicmap: arquivos map e html que são utilizados na inicialização e em algumas operações que necessitam de mapas básicos, utilizados como se fossem templates.
* classesjs: programas em JavaScript utilizados no controle da interface principal.
* classesphp: programas em PHP utilizados pelas ferramentas e pela interface principal.
* css: arquivos do tipo css com os estilos de formatação das páginas html.
* documentação: documentação do sistema.
* ferramentas: arquivos html, javaScript PHP utilizados em funções específicas, geralmente abertas como janelas internas na interface principal da aplicação.
* imagens: ícones e demais figuras.
* menutemas: arquivos utilizados na criação do menu para adição de temas.
* pacotes: arquivos dos pacotes de terceiros integrados ao I3Geo.
* symbols: arquivos com a simbologia utilizada na representação dos temas no mapa.
* temas: arquivos .map correspondentes aos temas disponíveis para inclusão no mapa.
* exemplos: arquivos com exemplos de uso e customização do I3Geo.

### Utilização do R
## Configuração
### Inclusão de temas (camadas)

Alguns arquivos no formato shape file são fornecidos junto com o I3Geo possibilitando a geração de um mapa do Brasil. Esses dados são utilizados apenas para demonstrar que o mapa interativo está funcionando, devendo ser feita a adequação dos mesmos para atender as necessidades dos usuários do sítio que está sendo construído.
Os formatos de dados que podem ser visualizados no I3Geo são os mesmos aceitos pelo Mapserver, que por sua vez, utiliza as bibliotecas OGR, GDAL e implementações próprias de acesso a dados.
Tendo os dados preparados e organizados, seja na forma de arquivos ou bancos de dados, é possível incluir no menu de adição de temas as camadas desejadas. Para isso, é necessário a criação de arquivos do tipo mapfile, que definem os parâmetros de apresentação de uma camada, e a organização desses no arquivo XML usado pelo I3Geo na apresentação do menu.

#### Configuração de uma camada

Para cada nova camada a ser incluída no I3Geo, deve-se criar um arquivo mapfile e armazená-lo no diretório i3geo\temas.
Um arquivo mapfile típico é mostrado a seguir (note que esse arquivo não precisa de todas as TAGS exigidas pelo Mapserver).
Arquivo municip.map: (o caractere # indica uma linha comentada)

#### Inclusão de camadas no menu de temas

Após a criação do arquivo .map, com a representação do tema, é necessário editar o arquivo menutemas/menutemas.xml, para que a nova camada fique disponível no menu de adição de temas.
O arquivo menutemas.xml utiliza o formato XML, podendo ser manipulado com qualquer editor de textos. Como XML, a estrutura do texto deve ser bem formada, respeitando-se a hierarquia de itens e seu correto fechamento, como no exemplo abaixo:
O XML é organizado em grupos, subgrupos e temas, sendo que em cada nível existem atributos específicos, como mostrado abaixo:
Não existem limites para o número de temas em um menu e sempre deve haver grupos e subgrupos para organizar os temas, mesmo que exista apenas um tema. O arquivo XSL indicado no início do XML não é utilizado pelo i3Geo, podendo ser customizado para outro tipo de representação que for de interesse.
A estruturação do arquivo menutemas.xml deve ser feita com cuidado, uma vez que erros na hierarquia ou no fechamento/abertura dos itens, podem gerar problemas. Para verificar se o arquivo está correto, pode-se utilizar o próprio navegador de internet para visualizá-lo. Caso ocorra algum problema, o navegador irá apontar o erro, caso contrário, tem-se uma visualização como mostrado na imagem abaixo. Observe ainda que o caractere &, utilizado muitas vezes na criação de links, deve ser substituído por & amp;, caso contrário, o interpretador XML provocará um erro na abertura.
Na versão 3.3 do I3Geo, os temas podem ser incluídos fora dos grupos e subgrupos, ou seja, podem existir temas sem pai na hierarquia do XML.
O arquivo com os temas é também utilizado pelo programa i3geo/ogc.php, que gera 'WEB Services' nos padrões OGC, automaticamente. Se vc não deseja que determinado tema seja incluído na lista de camadas dos web services, é necessário incluir nesse tema o item:
Você pode também criar perfis, assim os temas serão mostrados no menu apenas quando o perfil for o mesmo da variável de inicialização 'perfil'. Para utilizar um perfil, basta acrescentar o item <PERFIL>, como mostrado abaixo:
menutemas/menutemas.xml, para que a nova camada fique disponível no menu de adição de temas.
O arquivo menutemas.xml utiliza o formato XML, podendo ser manipulado com qualquer editor de textos. Como XML, a estrutura do texto deve ser bem formada, respeitando-se a hierarquia de itens e seu correto fechamento, como no exemplo abaixo:
O XML é organizado em grupos, subgrupos e temas, sendo que em cada nível existem atributos específicos, como mostrado abaixo:
Os perfis podem ser incluídos em qualquer nível, ou seja, subgrupo e tema. Para indicar o perfil para o I3Geo, na inicialização deve-se usar a variável &perifl, exemplo:

### Inclusão de endereços para conexão remota

No menu de adição de temas do i3Geo existe uma opção que possibilita ao usuário acessar um tema a partir de uma conexão com um serviço no padrão OGC (WMS) e também via Geo RSS.
Para incluir um RSS na lista que aparece no menu de seleção, aberto quando o usuário clica no item Conectar com WMS ou Conectar com GeoRSS, é necessário editar o arquivo i3geo/ferramentas/conectarwms/index.htm e i3geo/ferramentas/conectargeorss/index.htm, respectivamente. Esses arquivos são HTMLs que contém a lista de serviços e o endereço, como mostrado no exemplo abaixo.
Para adicionar um serviço basta incluir um novo item no array, seguindo o exemplo já existente, para excluir, basta apagar o item.
Por padrão, o I3Geo busca a lista de serviços no arquivo menutemas/servicoswms.xml e menutemas/servicosgeorss.xml
Para incluir um serviço ou excluir, basta editar esse arquivo.

### Inclusão de aplicações que adicionam novas camadas

No menu de adição de temas, após a árvore Temas é incluída a árvore sistemas. Nessa árvore são listados aplicativos que quando executados geram novas camadas de temas. Assim, é possível iniciar uma aplicação com diálogos e processos específicos para a adição de temas.
A lista de aplicações incluídas no item sistemas é buscada no arquivo menutemas/sistemas.xml. Da mesma forma que o arquivo menutemas.xml, descrito anteriormente, o arquivo sistemas.xml segue a formatação XML, com a estrutura mostrada abaixo.
Caso não existam aplicações para adicionar no menu, o arquivo 'ms_congigura.php deve ser alterado (veja tópico específico sobre a instalação e configuração do i3Geo).
Como pode-se observar no exemplo acima, é possível a inclusão de dois níveis na árvore que aparece no menu. O primeiro nível é nominado pelo item <NOMESIS> e o segundo por <NOMEFUNCAO>. Para cada novo grupo de aplicações, é necessário incluir um item <SISTEMA> </SISTEMA> e para cada nova função um item <FUNCAO></FUNCAO>. Quando uma função é escolhida pelo usuário, o programa indicado em <ABRIR> é executado em uma janela integrada no i3Geo, os itens <JANELAW> e <JANELAH> controlam o tamanho dessa janela (largura e altura respectivamente).
Tanto no nível SISTEMA como em FUNCAO, pode-se incluir uma lista, separada por vírgulas, dos perfis de usuário que podem acessar o sistema ou função. O perfil do usuário atual do mapa é definido na inicialização do I3Geo.

### Inclusão de aplicações no menu de identificação

De forma semelhante à inclusão de aplicações no menu de adição de temas, é possível incluir na janela de identificação opções que fazem um processamento especial tendo como base o ponto clicado no mapa.
Para adicionar uma aplicação na janela de identificação, é necessário indicar no arquivo ms_configura.php o endereço do arquivo XML (por padrão menutemas/identifica.xml) que contém a lista de aplicações. Esse arquivo XML deve ser formatado como no exemplo:
Observe que o programa “r.php” utiliza os parâmetros 'x' e 'y' que são obtidos das variáveis 'xpt' e 'ypt', fornecidas pelo próprio I3Geo.

### Fontes

As fontes para o desenho de textos no mapa, são armazenadas no diretório symbols. As fontes distribuídas com o I3Geo são todas livres, mas você pode acrescentar outras fontes. Para isso, vc deve:
* Copiar o arquivo com a fonte no diretório symbols.
* Editar o arquivo fontes.txt, acrescentando as novas fontes.

### Escondendo a string de conexão com o banco de dados

Em função de uma característica do Mapserver, a string de conexão com o banco de dados é incluída no arquivo mapfile, ficando exposta e podendo ser visualizada em algumas situações.
Essa característica, apesar de não representar problemas de segurança, pode não ser desejada em algumas situações.
O I3Geo, a partir da versão 3.6, implementa um esquema que possibilita esconder a string de conexão em bancos Postgis. Para que isso ocorra, é necessário incluir no arquivo ms_configura.php a varíável $postgis_mapa, como por exemplo:
$postgis_mapa = "user=geo password=geo dbname=geo host=localhost port=5432";
Caso não exista a necessidade de implementar esse esquema de substituição, deve-se manter a variável como:
$postgis_mapa = "";
Além dessa variável, é necessário excluir dos arquivos mapfile (existentes em i3geo/temas) a string de conexão, por exemplo:
CONNECTION " "

## Programas especiais

Programas criados para automatizar operações de manutenção do I3Geo:
* classesjs/compactajs.php: compacta os arquivos javaScript (.js) eliminando caracteres dispensáveis, diminuindo o tamanho dos mesmos e aumentando a velocidade de carga da aplicação. Deve ser executado sempre que ocorrer alterações nos arquivos não compactados existentes no diretório classesjs.
* testainstal.php: faz um teste básico da instalação do I3Geo.

## Documentação

A documentação dos códigos do I3Geo utiliza o pacote NaturalDocs [www.naturaldocs.org ver]. Instale o NaturalDocs em c:\naturaldocs e execute o programa c:\ms4w\apache\htdocs\i3geo\documentacao\js\local.bat para atualizar a documentação.

## Atualização

Para atualizar o I3Geo basta fazer o download da nova versão e copiar os arquivos para os locais adequados. Geralmente não se deve alterar os arquivos de configuração, como o ms_configura e aqueles existentes no diretório aplicmap. Para não perder o menu com os temas e os arquivos correspondentes aos temas, não sobreponha os diretórios menutemas e temas com a nova versão.

## Inicialização do I3Geo

A inicialização do i3Geo é feita sempre pelo programa i3geo/ms_criamapa.php, esse programa utiliza parâmetros de inicialização (ver documentação dos códigos PHP) que podem alterar a apresentação do mapa, tais como a extensão geográfica, temas já ativos, temas que iniciam de forma visível, etc.
Ao iniciar o mapa, são criados diretórios temporários no endereço de arquivos temporários do Mapserver. Nesses diretórios são copiados os arquivos necessários para o funcionamento do i3geo, principalmente o arquivo 'mapfile' inicial (por padrão 'aplicmap/geral1.map' ou 'aplicmap/geral1windows.map'). As funções do mapa interativo utilizam esse 'mapfile' temporário para recuperar os parâmetros necessários ao desenho do mapa.
Esse esquema garante uma grande flexibilidade para a aplicação, pois qualquer função de processamento pode ler e gravar no arquivo de mapa temporário, não havendo interferências entre mapas ou limites quanto ao número de temas disponíveis ao usuário.
Exemplos:
* Inicialização normal: utiliza os parâmetros padrão
* Inicialização com debug: ativa o modo de debug nos programas em PHP que rodam no servidor. Isso permite o uso de programas como o Firebug, do Firefox, para verificação mais detalhada de erros
* Inicialização com temas adicionais: abre o mapa já com alguns temas incluídos
* Inicialização com temas adicionais e temas visíveis: inclui temas e torna-os visíveis
* Inicialização enquadrando o mapa: altera a extensão geográfica padrão
* Inicialização adicionando pontos: mostra pontos no mapa
* Inicialização com uma interface diferente: utiliza uma "cara" diferente para o mapa
* Mapfile diferente: utiliza um mapfile específico na inicialização
No diretório i3geo/exemplos existem alguns exemplos que mostram maneiras de customizar a iniciallização do I3Geo. Além dos links mostrados acima, é possível iniciallizar o I3Geo incluindo programas em PHP ou funções que serão executados. Um exemplo dessa forma de inicialização é mostrado em i3geo/exemplos/executafuncao.php.

### Processo de inicialização

1.Inclui o arquivo de funções 'classesphp/funcoes_gerais.php'.
2.Processa as variáveis de sessão.
3.Apresenta a mensagem de 'aguarde' caso o parâmetro 'interface' não esteja definido.
4.Verifica se os arquivos de configuração existem, caso contrário, aborta a inicialização.
5.Inclui o arquivo 'ms_configura.php'.
6.Verifica o sistema operacional do servidor para definir qual arquivo 'mapfile' deve ser utilizado na inicialização.
7.Verifica se os parâmetros de inicialização foram especificados ou não, nesse último caso, utiliza os parâmetros padrão.
8.Cria os arquivos temporários no diretório 'ms_tmp'.
9.Verifica se devem ser incluídos novos temas no mapa padrão e faz a inclusão.
10.Verifica quais temas devem aparecer ligados na inicialização do mapa.
11.Aplica os parâmetros identificados no item 6.
12.Salva o 'mapfile' temporário.
13.Verifica se existe algum programa ou função que deve ser executado sobre o arquivo 'mapfile' criado (parâmetro de inicialização executa).
14. Caso existam programas, os mesmos são incluídos. Esses programas podem operar sobre o arquivo 'mapfile' criado (variável $tmpfname).
15. Abre o mapa no navegador.

## Configuração da apresentação

A apresentação do mapa é definida em arquivos HTML e CSS. Esses arquivos podem ser alterados ou criados outros para a customização da apresentação do mapa. Os arquivos CSS utilizados estão no diretório “css” e podem ser modificados conforme o desejado.
O arquivo HTML padrão utilizado nos mapas é o “aplicmap/geral.htm”. Esse arquivo está comentado de forma a tornar-se auto-explicativo. Os botões de ferramentas e outras funcionalidades do mapa podem ser excluídos ou reposicionados sem prejuízos no funcionamento do I3Geo.
Nesse arquivo HTML existem uma série de variáveis que podem alterar algumas características da interface, por exemplo, não abrir o mapa de referência, não abrir a janela de mensagens, iniciar com determinada guia aberta, etc.

### Acesso ao GoogleMaps

Para que a ferramenta de integração com o Google Maps funcione, é necessário cadastrar o servidor onde está rodando o I3Geo no google veja.
Recebida a chave de acesso, basta incluí-la no arquivo i3geo/ferramentas/googlemaps/index.htm, na linha:

### Visualização em 3D

A visualização em 3d (ou melhor, 2.5d) é ainda experimental no I3Geo. A sua implementação é baseada na criação de um arquivo wmrl no lado do servidor, após o arquivo ter sido gerado, é indicado o link para o usuário acessar o arquivo. Para que o modelo 3d possa ser visto, o usuário precisa ter instalado em sua máquina um programa ou plugin para o navegador de internet que estiver usando.
Para a geração do modelo wmrl, o I3Geo utiliza um arquivo .map que contém o tema com os valores de Z. O nome desse arquivo é definido na variável g_3dmap existente no arquivo aplicmap/geral.htm, por default, essa variável é definida como g_3dmap = "3dmap.map";.

## Sistemas integrados
### Cliente de web service

Com o "WSCliente" é possível acessar serviços que retornam dados textuais e mapas, sendo utilizado para cadastrar, divulgar e fornecer um meio rápido de verificação dos serviços disponíveis.
A inclusão dos links para os serviços utiliza o padrão RSS, dessa forma, os serviços de cada instituição podem ser incluídos e atualizados permanentemente.
Para acessar o cliente utilize o endereço
Para incluir serviços na lista disponível veja a documentação incluída no próprio arquivo html.

### Download de dados

Essa aplicação lê o arquivo menutemas.xml e lista os temas que permitem download. É uma aplicação útil para fornecer aos usuários o acesso aos dados. A aplicação pode ser configurada também para mostrar links para outras bases de dados, nesse caso, a lista de links pode ser mantida no arquivo menutemas/linksdownload.xml.
O endereço para acesso é:

### Gerador automático de Web services OGC

Com base nos temas incluídos no menutemas.xml, esse aplicativo gera automaticamente webservices no padrão OGC. Para ver a sintaxe desse programa, utilize:
O endereço do web service é
Caso você queira um web service de um tema específico, utilize:
O código do tema corresponde ao código existente no arquivo menutemas.xml.
Para evitar que um número muito grande de temas seja incluído, você pode especificar um range, por exemplo:

### Gerador de links

O gerador de links é uma aplicação que possibilita ao usuário criar, de forma interativa, links customizados para abrir o I3Geo. Na interface pode-se escolher os temas que farão parte do mapa, definir a abrangência espacial, etc.
Exemplo:

## FAQ
#### Eu posso alterar os códigos do I3Geo e redistribuí-lo?

Sim. O I3Geo é licenciado como GPL, estando sujeito as regras desse tipo de licença.

#### Como eu posso testar a instalação do I3Geo?

Rode o programa i3geo/testainstal.php no seu navegador.

#### Criei um tema mas não consigo ver no I3Geo, como posso testar esse tema?

Rode o programa i3geo/testamapfile.php, disponível na versão 2.9.

#### O I3Geo está abrindo corretamente, mas a imagem do mapa não aparece, qual o problema?

Provavelmente o Apache não está reconhecendo o diretório ms_tmp como um diretório web. Crie um link simbólico no mesmo diretório onde está o i3geo apontando para o ms_tmp.

#### Com o tempo o diretório ms_tmp fica cheio, o que devo fazer?

O diretório ms_tmp é usado para armazenar os dados temporários de cada mapa, você deve apagá-lo de tempos em tempos, o que pode ser feito de forma automática, utilize algum programa do seu sistema operacional para programar essa limpeza.

#### A opção de inclusão de textos não funciona

Provavelmente as fontes existentes no diretório i3geo/symbols não são adequadas ao seu sistema operacional. Copie para esse diretório outras fontes existentes no seu sistema.

#### A guia 'mapas' não mostra nada

Edite o arquivo ms_configura e defina a variável de busca do arquivo xml para o local de sua instalação.