.. ----------------------------------------------
.. -----------------  GEO  ---------------------
.. ----------------------------------------------

.. only:: html
    
    .. image:: /img/arquivos.png

.. _geo:

Arquivo de Dados Geográficos
----------------------------

.. sidebar::  Ficha descritiva: GEO

    .. only:: html

        .. figure:: /introducao/arquivos/img/arquivos_csv.png
            :width: 60 %
            :align: center

    .. only:: latex

        .. figure:: /introducao/arquivos/img/arquivos_csv.png
            :scale: 15 %
            :align: center

    ===================  =====
    **Número ULOG**      \-
    **Tipo no DARQ**     GEO
    **Extensão**         .json
    **Nome automático**  Não
    ===================  =====
    
    **Arquivo de dados geográficos para a Visão Geoespacial do Anatem**

O arquivo ``GEO`` contém a associação entre as entidades elétricas do caso e
os elementos utilizados na representação geográfica. Ele é consumido pela
Visão Geoespacial do Anatem e não participa do cálculo elétrico realizado
pelo Anatem.

A associação é declarada pelo código :ref:`DARQ`, utilizando o tipo ``GEO``.
O caminho relativo do arquivo é resolvido a partir do STB principal:

.. code-block:: anatem
    :caption: Declaração de arquivo de dados geográficos

    DARQ
    (Tipo) (C) ( Arquivo
    OUT        caso.out
    PLT        caso.plt
    GEO        caso.geo.json
    999999

O Anatem instala dois arquivos de referência na pasta ``geography``:

``network-geography.schema.json``
    Descreve a estrutura aceita para um arquivo GEO, os campos disponíveis e
    as relações obrigatórias entre eles. O schema serve para conferir o
    formato do arquivo; ele não contém a geografia de um caso e não participa
    do cálculo elétrico.

``Caso_1Q2026.geo.json``
    Base geográfica genérica construída para o caso SIN de referência.

Os nomes das chaves permanecem em inglês no arquivo JSON, pois fazem parte do
formato GEO. A interface e este manual apresentam os mesmos conceitos em
português:

==============  =====================  ========================================
Chave no JSON   Nome na interface      Associação elétrica
==============  =====================  ========================================
``nodes``       Nós geográficos        Posições que podem reunir várias barras
``buses``       Barras elétricas       Barras identificadas pelo ``RBAR``
``trunks``      Troncos geográficos    Geometrias compartilháveis
``circuits``    Circuitos elétricos    Circuitos identificados pelo ``RLIN``
==============  =====================  ========================================

As coordenadas e geometrias devem preservar sua proveniência. Uma posição pode
ser classificada como exata, aproximada ou não mapeada. A posição aproximada é
uma inferência rastreável a partir de uma barra-âncora e não deve ser
interpretada como levantamento cadastral. Barras sem associação defensável
permanecem no inventário elétrico, mas não recebem coordenadas inventadas.

Base genérica do SIN
====================

Para o caso SIN de referência, a base ``Caso_1Q2026.geo.json`` pode ser
utilizada com a Visão Geoespacial. Ela combina o inventário de barras, a
topologia do caso e uma fotografia pública de coordenadas de subestações.

Construída a partir de dados públicos, essa base serve para visualização
ilustrativa e análise exploratória. Ela não representa uma promessa de
atualização cadastral nem substitui uma base específica ou oficial. Sua
versão, proveniência, licença e data de obtenção acompanham o arquivo
distribuído.

A definição e a distribuição das bases geográficas adequadas a cada estudo
ficam a critério dos provedores oficiais das bases elétricas correspondentes,
como o ONS e a EPE. Quando houver uma base específica disponibilizada por
essas fontes, ela deve ser preferida à referência genérica do Anatem.

Quando não há um arquivo GEO declarado para o caso, o Anatem pode oferecer
essa base instalada. A confirmação do usuário é necessária porque a rede, a
configuração e a época do estudo aberto podem ser diferentes da referência.
Também é possível copiar a base para o estudo e declará-la no ``DARQ``:

.. code-block:: anatem
    :caption: Associação da base geográfica genérica do SIN

    DARQ
    GEO        Caso_1Q2026.geo.json
    999999

Uso dos resultados
==================

Os resultados do Dashboard podem ser associados às barras e circuitos
representados no arquivo GEO. Tensão, frequência e ângulo podem controlar cor,
tamanho ou destaque visual. Essas propriedades são apenas uma forma de
apresentação:

* não alteram os valores do ``OUT`` ou do ``PLT``;
* não criam resultados entre duas barras;
* não transformam proximidade geográfica em conectividade elétrica;
* não substituem as identidades autoritativas do ``RBAR`` e do ``RLIN``.

O mapa é operado localmente. A utilização do arquivo GEO não consulta serviços
externos, bases públicas online, tiles ou serviços de geocodificação durante a
execução.

.. note::

    O arquivo GEO é utilizado pela interface do Anatem. O conteúdo geográfico
    não é uma entrada numérica do cálculo do Anatem e não modifica a simulação.

.. versionadded:: 13.0.0
    Foi introduzido o arquivo de dados geográficos ``GEO``, declarado por
    :ref:`DARQ`, para fornecer a base local da Visão Geoespacial do Anatem.