# Exemplos de Uso - GeoServiço-CLIPPER\n\n## Exemplo 1: Recortar MapBiomas para uma Propriedade Rural\n\n### Cenário\nVocê tem um shapefile com os limites de uma propriedade rural e quer analisar o uso do solo MapBiomas para os últimos 5 anos.\n\n### Passo a Passo\n\n1. **Preparar os dados**\n   - Abra QGIS\n   - Vá para **Arquivo** → **Abrir Projeto** ou crie um novo projeto\n   - Importe o shapefile da propriedade: **Camada** → **Adicionar Camada** → **Adicionar Camada Vetorial**\n\n2. **Abrir o plugin**\n   - Vá para **Plugins** → **GeoServiço-CLIPPER** → **GeoServiço-CLIPPER - Recortar MapBiomas**\n\n3. **Configurar parâmetros**\n   - **Camada Vetorial**: Selecione o shapefile da propriedade\n   - **Ano**: 2024 (ou o ano desejado)\n   - **Coleção**: Collection 10 (Recomendado)\n   - **Arquivo de Saída**: Deixe como \"Arquivo temporário\" ou especifique um caminho\n\n4. **Processar**\n   - Clique em **\"Recortar MapBiomas\"**\n   - Aguarde o processamento (pode levar alguns minutos)\n   - A imagem recortada será adicionada automaticamente ao projeto\n\n5. **Analisar resultados**\n   - A imagem aparecerá como uma nova camada no painel de camadas\n   - Use a ferramenta de seleção para analisar os valores de classe\n   - Consulte a legenda de classificação na aba \"Informações\"\n\n### Código Python (Alternativa)\n\n```python\n# No console Python do QGIS\nfrom qgis.core import QgsProject, QgsVectorLayer\nfrom geosservico_clipper.earth_engine_handler import EarthEngineHandler\n\n# Carregar camada vetorial\nproject = QgsProject.instance()\nlayer = project.mapLayersByName('propriedade')[0]\n\n# Inicializar Earth Engine Handler\nee_handler = EarthEngineHandler()\n\n# Obter geometrias\nfeatures = layer.getFeatures()\ngeometries = [feature.geometry() for feature in features]\n\n# Recortar MapBiomas\nsuccess = ee_handler.clip_mapbiomas(\n    geometries=geometries,\n    year=2024,\n    output_path='/caminho/para/saida.tif'\n)\n\nif success:\n    print(\"Recorte concluído com sucesso!\")\nelse:\n    print(\"Falha ao processar recorte\")\n```\n\n---\n\n## Exemplo 2: Análise Temporal de Mudanças de Uso do Solo\n\n### Cenário\nVocê quer comparar o uso do solo em uma região para múltiplos anos (2010, 2015, 2020, 2024) para identificar tendências.\n\n### Passo a Passo\n\n1. **Preparar máscara**\n   - Importe um shapefile ou GeoJSON com os limites da região de interesse\n\n2. **Processar para cada ano**\n   - Abra o plugin\n   - Selecione a camada de máscara\n   - Para cada ano (2010, 2015, 2020, 2024):\n     - Altere o valor do **Ano**\n     - Especifique um caminho de saída diferente (ex: `mapbiomas_2010.tif`, `mapbiomas_2015.tif`, etc.)\n     - Clique em **\"Recortar MapBiomas\"**\n     - Aguarde a conclusão\n\n3. **Comparar resultados**\n   - Todas as imagens estarão carregadas como camadas no projeto\n   - Use a ferramenta de alternância de visibilidade para comparar\n   - Crie um mapa de diferenças usando a calculadora raster\n\n### Código Python (Análise Automática)\n\n```python\n# No console Python do QGIS\nfrom qgis.core import QgsProject, QgsRasterLayer\nfrom geosservico_clipper.earth_engine_handler import EarthEngineHandler\nimport os\n\n# Configuração\noutput_dir = '/caminho/para/saida'\nyears = [2010, 2015, 2020, 2024]\nlayer = QgsProject.instance().mapLayersByName('regiao')[0]\n\n# Inicializar Earth Engine Handler\nee_handler = EarthEngineHandler()\n\n# Obter geometrias\nfeatures = layer.getFeatures()\ngeometries = [feature.geometry() for feature in features]\n\n# Processar para cada ano\nfor year in years:\n    output_path = os.path.join(output_dir, f'mapbiomas_{year}.tif')\n    \n    print(f\"Processando ano {year}...\")\n    success = ee_handler.clip_mapbiomas(\n        geometries=geometries,\n        year=year,\n        output_path=output_path\n    )\n    \n    if success:\n        # Carregar como camada\n        layer = QgsRasterLayer(output_path, f'MapBiomas {year}')\n        QgsProject.instance().addMapLayer(layer)\n        print(f\"✓ Ano {year} processado com sucesso\")\n    else:\n        print(f\"✗ Erro ao processar ano {year}\")\n\nprint(\"Análise temporal concluída!\")\n```\n\n---\n\n## Exemplo 3: Monitoramento de Desflorestamento\n\n### Cenário\nVocê quer monitorar a perda de floresta em uma área de conservação comparando dois anos.\n\n### Passo a Passo\n\n1. **Preparar dados**\n   - Importe um shapefile com os limites da área de conservação\n   - Processe MapBiomas para 2020 e 2024\n\n2. **Criar índice de mudança**\n   - Use a **Calculadora Raster** do QGIS\n   - Crie uma expressão para identificar pixels que eram floresta em 2020 mas não são em 2024\n   - Exemplo: `(mapbiomas_2020@1 == 3) AND (mapbiomas_2024@1 != 3)`\n     (Onde 3 = Formação Florestal)\n\n3. **Quantificar desflorestamento**\n   - Use a ferramenta **Estatísticas de Camada Raster**\n   - Calcule a área em pixels\n   - Multiplique por 900 (30m × 30m) para obter área em m²\n   - Divida por 10.000 para obter em hectares\n\n### Código Python (Análise Automática)\n\n```python\n# No console Python do QGIS\nimport numpy as np\nfrom osgeo import gdal\nfrom qgis.core import QgsProject, QgsRasterLayer\n\n# Carregar rasters\nraster_2020 = gdal.Open('/caminho/para/mapbiomas_2020.tif')\nraster_2024 = gdal.Open('/caminho/para/mapbiomas_2024.tif')\n\n# Ler dados\nband_2020 = raster_2020.GetRasterBand(1).ReadAsArray()\nband_2024 = raster_2024.GetRasterBand(1).ReadAsArray()\n\n# Identificar desflorestamento (3 = Formação Florestal)\nfloresta_2020 = (band_2020 == 3)\nfloresta_2024 = (band_2024 == 3)\n\n# Pixels que eram floresta em 2020 mas não são em 2024\ndesflorestamento = floresta_2020 & ~floresta_2024\n\n# Calcular área em hectares\npixels_desmatados = np.count_nonzero(desflorestamento)\narea_m2 = pixels_desmatados * 900  # 30m × 30m\narea_ha = area_m2 / 10000\n\nprint(f\"Pixels desmatados: {pixels_desmatados}\")\nprint(f\"Área desmatada: {area_ha:.2f} hectares\")\n```\n\n---\n\n## Exemplo 4: Análise de Agricultura\n\n### Cenário\nVocê quer identificar e quantificar áreas de agricultura em uma região.\n\n### Passo a Passo\n\n1. **Processar MapBiomas**\n   - Abra o plugin\n   - Selecione a camada de máscara (região de interesse)\n   - Escolha o ano desejado (ex: 2024)\n   - Clique em **\"Recortar MapBiomas\"**\n\n2. **Filtrar classes agrícolas**\n   - Use a **Calculadora Raster** para criar uma máscara de agricultura\n   - Classes agrícolas: 18 (Agricultura), 20 (Cana-de-Açúcar), 39 (Soja), 40 (Arroz), 46 (Café), 47 (Citrus), 62 (Algodão)\n   - Expressão: `(mapbiomas@1 == 18) OR (mapbiomas@1 == 20) OR (mapbiomas@1 == 39) OR (mapbiomas@1 == 40) OR (mapbiomas@1 == 46) OR (mapbiomas@1 == 47) OR (mapbiomas@1 == 62)`\n\n3. **Quantificar**\n   - Use **Estatísticas de Camada Raster**\n   - Calcule a área total de agricultura\n\n### Código Python\n\n```python\n# No console Python do QGIS\nimport numpy as np\nfrom osgeo import gdal\n\n# Carregar raster\nraster = gdal.Open('/caminho/para/mapbiomas_2024.tif')\nband = raster.GetRasterBand(1).ReadAsArray()\n\n# Classes agrícolas\nclasses_agricolas = [18, 20, 39, 40, 46, 47, 62]\n\n# Criar máscara\nagricultura = np.zeros_like(band, dtype=bool)\nfor classe in classes_agricolas:\n    agricultura |= (band == classe)\n\n# Calcular área\npixels_agricolas = np.count_nonzero(agricultura)\narea_ha = (pixels_agricolas * 900) / 10000\n\nprint(f\"Pixels agrícolas: {pixels_agricolas}\")\nprint(f\"Área agrícola: {area_ha:.2f} hectares\")\n\n# Estatísticas por classe\nfor classe in classes_agricolas:\n    pixels = np.count_nonzero(band == classe)\n    area = (pixels * 900) / 10000\n    print(f\"Classe {classe}: {area:.2f} ha\")\n```\n\n---\n\n## Exemplo 5: Integração com Processing Framework\n\n### Cenário\nVocê quer usar o plugin como parte de um fluxo de trabalho automatizado no Processing do QGIS.\n\n### Passo a Passo\n\n1. **Abrir Processing**\n   - Vá para **Processing** → **Toolbox**\n\n2. **Procurar algoritmo**\n   - Na caixa de busca, digite \"mapbiomas\"\n   - Encontre \"Recortar MapBiomas\"\n\n3. **Configurar parâmetros**\n   - **Camada Vetorial**: Selecione a camada\n   - **Ano**: 2024\n   - **Coleção**: 10\n   - **Arquivo de Saída**: Especifique o caminho\n\n4. **Executar**\n   - Clique em **\"Run\"**\n   - O resultado será adicionado ao projeto\n\n### Usar em Modelo do Processing\n\n```\n1. Abra **Processing** → **Graphical Modeler**\n2. Adicione o algoritmo \"Recortar MapBiomas\"\n3. Conecte a entrada de camada vetorial\n4. Configure os parâmetros\n5. Salve o modelo\n6. Use o modelo em futuros projetos\n```\n\n---\n\n## Dicas e Boas Práticas\n\n### Performance\n- **Geometrias menores processam mais rápido**: Se possível, divida grandes áreas em polígonos menores\n- **Evite geometrias muito complexas**: Simplifique polígonos com muitos vértices\n- **Processamento em lote**: Use scripts Python para processar múltiplos anos automaticamente\n\n### Qualidade de Dados\n- **Validar geometrias**: Certifique-se de que os polígonos são válidos (sem auto-interseções)\n- **Verificar CRS**: O plugin trabalha com EPSG:4326, mas reprojetar é automático\n- **Revisar resultados**: Sempre visualize e valide os resultados antes de usar em análises\n\n### Armazenamento\n- **Salvar resultados**: Especifique um caminho de saída para manter os arquivos\n- **Organizar arquivos**: Crie uma estrutura de pastas por ano ou região\n- **Backup**: Faça backup dos arquivos importantes\n\n---\n\n## Recursos Adicionais\n\n- [Documentação MapBiomas](https://brasil.mapbiomas.org)\n- [Google Earth Engine](https://earthengine.google.com)\n- [QGIS Documentation](https://docs.qgis.org)\n- [PyQGIS Cookbook](https://docs.qgis.org/latest/en/docs/pyqgis_developer_cookbook/)\n\n---\n\n**Desenvolvido com ❤️ para a comunidade geoespacial brasileira**\n
