Pt:Introdução ao openstreetmap-carto

O projeto openstreetmap-carto define o estilo da Camada do mapa Padrão exibido para os usuários quando visitam o site do OpenStreetMap. Os dados cartográficos mapeados pelos usuários da plataforma são convertidos em imagens e exibidos no site do projeto e em sites de terceiros que utilizem a mesma renderização padrão.

O objetivo deste pequeno tutorial é ser uma introdução ao desenvolvimento do projeto, afim de testar e sugerir mudanças na forma como o mapa é apresentado - ou seja, como os dados cartográficos são transformados em imagens - em sua apresentação padrão.

Este tutorial assume algum conhecimento de ferramentas de linha de comando / terminal. Por favor utilize a página de discussão para dúvidas sobre algum passo que não tenha ficado claro, afim de que possamos construi-lo coletivamente.

Os passos assumem um sistema operacional GNU/Linux usando a distribuição Ubuntu (versão LTS mais recente); usuários Windows podem utilizar a ferramenta WSL2 (Windows Subsystem for Linux) para seguir exatamente os mesmos passos. Este tutorial foi escrito utilizando o Ubuntu rodando no Windows 11 através do WSL2 para garantir a máxima compatibilidade entre os sistemas operacionais. Usuários de outras distribuições poderão adaptar os comandos de instalação de pacotes. Opcionalmente e de forma similar, no Linux, você pode criar uma máquina virtual para que eventuais testes não alterem a sua instalação principal.

Toda vez que um comando for apresentado, você deverá entrá-lo na janela do terminal, isto é, copiar e colar o comando e pressionar Enter.

Passo a passo

Instalar o WSL 2 (somente Windows)

(Usuários Linux podem pular este passo.)

1. Abrir o menu Iniciar, procurar por "Prompt de Comando", clicar com o botão direito e escolher a opção "Executar como administrador"
2. Entrar o comando: wsl --install

Com isso será feita a instalação do Ubuntu através do WSL2, e você terá um ambiente Linux de linha de comando dentro do Windows. Após a instalação do Ubuntu terminar, você precisará reiniciar seu computador.

Baixando o openstreetmap-carto

O passo seguinte é abrir um terminal e baixar uma cópia do projeto openstreetmap-carto do github.

1. No Windows, abra o menu Iniciar, digite Ubuntu e aperte Enter. Caso você utilize Linux em seu computador, abra o Terminal.
2. Vá para a sua pasta de usuário*: cd ~
3. Atualize a lista de pacotes disponíveis: sudo apt update (será necessário digitar a senha do seu usuário)
4. Instale o git: sudo apt install git
5. Clone o repositório openstreetmap-carto: git clone https://github.com/gravitystorm/openstreetmap-carto.git

* O motivo do passo 2: por padrão, o WSL abre o terminal na pasta do usuário no Windows (/mnt/C/Users/nome-do-usuario). Caso instalemos nessa pasta, que tem o acesso espelhado com o Windows, isso ocasionará problemas de performance. É melhor instalar na pasta do usuário do Linux, que não é espelhada no Windows e portanto oferece maior performance. Caso você utilize Linux nativamente em seu computador, instale no diretório de sua preferência.

Baixando dados estáticos do OpenStreetMap

O objetivo do openstreetmap-carto é transformar dados cartográficos do OpenStreetMap em imagens, por isso precisamos de uma cópia parcial da base de dados do OpenStreetMap no computador. A base de dados de todo o planeta é gigantesca e seria desnecessário somente para testes, dessa forma podemos baixar somente um pequeno pedaço. Quanto menor a quantidade de dados, mais rápida será a renderização. Através do site Geofabrik, nós podemos baixar uma cópia dos dados somente do Brasil, ou somente de uma região geográfica (sudeste, nordeste etc).

1. Abra o site do Geofabrik e escolha uma área de sua preferência. Por exemplo, clique em South America (América do Sul), Brazil, se preferir, clique em uma região, e copie o link [.osm.pbf]
2. No terminal, instale o wget: sudo apt install wget
3. Entre na pasta do openstreetmap-carto: cd openstreetmap-carto
4. Baixe o arquivo: wget (cole o link)Por exemplo: wget https://download.geofabrik.de/south-america/brazil/sudeste-latest.osm.pbf

Dica: se você estiver utilizando o terminal do WSL no Windows, a combinação Ctrl+V para colar não irá funcionar. Você pode colar clicando no ícone da janela no canto superior direito > Editar > Colar.

Instalando dependências do banco de dados

Agora nós instalaremos uma série de programas que são necessários para o openstreetmap-carto funcionar, como o banco de dados PostgreSQL, assim como as fontes que são usadas para transformar texto em imagem.

1. Primeiro, vamos instalar as dependências: sudo apt-get install --no-install-recommends -y ca-certificates curl gnupg osm2pgsql gdal-bin python3-psycopg2 python3-yaml unzip python3-requests postgresql-client python3-distutils fonts-hanazono fonts-noto-cjk fonts-noto-hinted fonts-noto-unhinted mapnik-utils nodejs npm ttf-unifont
2. Agora iniciamos o banco de dados PostgreSQL: sudo service postgresql start
3. Após alguns segundos, verificamos se o PostgreSQL iniciou corretamente: pg_isready - a resposta deverá ser algo como /var/run/postgresql:5432 - accepting connections
4. Agora vamos entrar uma série de comandos para iniciar o banco de dados e prepará-lo para importar os dados do OpenStreetMap:
   1. psql -c "SELECT 1 FROM pg_database WHERE datname = 'gis';" | grep -q 1 || createdb gis
   2. createdb gis
   3. psql -d gis -c 'CREATE EXTENSION postgis; CREATE EXTENSION hstore;'

Importando banco de dados

Este é o passo em que você irá importar os dados do OpenStreetMap para a base de dados. Caso você queira atualizar a base de dados no futuro, basta baixar um novo arquivo .osm.pbf e executar este comando.

Note que isto demorará alguns minutos a depender da velocidade do seu computador e do tamanho da base de dados (se só uma região ou o país inteiro), pois importa todos os nós, vias e relações do OSM para a base de dados local.. A título de comparação, em um i7 com 32GB de RAM a importação da região sudeste levou 6 minutos.

1. Execute o comando: osm2pgsql -C 2048 -G --hstore --style openstreetmap-carto.style --tag-transform-script openstreetmap-carto.lua -d gis nome-do-arquivo.osm.pbf Por exemplo: osm2pgsql -C 2048 -G --hstore --style openstreetmap-carto.style --tag-transform-script openstreetmap-carto.lua -d gis sudeste-latest.osm.pbf

Caso você tente importar a base de dados do país inteiro, é possível que receba um erro Node cache size is too small to fit all nodes. Please increase cache size. Neste caso, altere o tamanho do cache mudando o parâmetro -C 2048 (que significa: tamanho de cache 2GB) para algum valor maior.

Continuando a configurar o banco de dados, arquivos auxiliares e outras dependências

Após a importação, precisamos alterar mais algumas configurações no banco de dados. Caso você importe novamente, não é necessário repetir estes passos.

1. psql -d gis -c 'ALTER SYSTEM SET jit=off;' -c 'SELECT pg_reload_conf();'
2. psql -d gis -f indexes.sql
3. Agora, executaremos alguns comandos que irão baixar uma série de dados auxiliares, como polígonos de costa do mar etc. scripts/get-external-data.py
4. Download de fontes: scripts/get-fonts.sh
5. Mais uma ferramenta para instalar, kosmtik: sudo npm set prefix /usr && npm install -g "git+https://git@github.com/kosmtik/kosmtik.git#f176c4c"
   1. Nota: caso você tenha instalado o nvm, você precisará fazer um link simbólico para a pasta /usr/lib, por exemplo: sudo ln -s /home/seu-usuario/.nvm/versions/node/v16.17.0/lib/node_modules/kosmtik /usr/lib/node_modules/kosmtikCaso você não saiba o que é nvm, não precisa se preocupar com este passo.
6. Baixando plugins do kosmtik: kosmtik plugins --install kosmtik-overpass-layer --install kosmtik-fetch-remote --install kosmtik-overlay --install kosmtik-open-in-josm --install kosmtik-map-compare --install kosmtik-osm-data-overlay --install kosmtik-mapnik-reference --install kosmtik-geojson-overlay

Quando você quiser atualizar a cópia dos dados locais, baixe novamente do site do Geofabrik (os dados são atualizados 1x por dia) baixando o arquivo e repetindo o passo da importação.

Executando o kosmtik

Finalmente, podemos executar o kosmtik para transformar os dados cartográficos em imagem. Entre o comando kosmtik serve project.mml --host 0.0.0.0 e abra o seu navegador no endereço http://localhost:6789. Você deverá ver um mapa mundi em branco, com dados somente na parte do mundo que realizou a importação dos dados, como no exemplo ao lado.

Os tiles ou "tijolos" do mapa, isto é, cada quadradinho de 256x256px que compõe o mapa, são gerados dinamicamente, por isso ao dar zoom no mapa você irá sentir uma certa lentidão em comparação a navegar direto no site do OpenStreetMap. Uma vez que você tenha visualizado uma dada região em um determinado nível de zoom as imagens já estarão armazenadas e a visualização será rápida.

Quando você reiniciar o computador e quiser trabalhar novamente na edição de estilos do openstreetmap-carto, este é o comando que precisará executar novamente para conseguir ver as alterações.

Modificando estilos

Neste ponto, nós vamos começar a editar uma série de arquivos de texto na linguagem de marcação utilizada pelo openstreetmap-carto, os Map StyleSheets (.mss). Se você tiver algum conhecimento ainda que básico sobre CSS (linguagem de marcação para estilização de páginas web), irá reconhecer as semelhanças.

Sugiro a utilização de algum editor de texto mais poderoso, uma IDE como o Visual Studio Code. Abrindo o VS Code, vá no menu Arquivo > Abrir pasta... e escolha a pasta openstreetmap-carto.

Dica: caso você esteja utilizando WSL, o Visual Studio consegue abrir os arquivos por dentro do Ubuntu sem nenhum problema, basta abrir a pasta \\wsl$, o pasta que representa a distribuição instalada (por exemplo, o padrão Ubuntu-20.04), e navegar para a pasta home, nome do seu usuário, e finalmente a pasta openstreetmap-carto.

(Continua)