Dados de ponto de clustering no SDK da Web

Quando há muitos pontos de dados no mapa, alguns podem se sobrepor uns aos outros. A sobreposição pode fazer com que o mapa se torne ilegível e difícil de usar. O clustering de dados de ponto são o processo de combinar dados de ponto que estão próximos uns dos outros e os representar no mapa como um ponto de dados clusterizado individual. À medida que o usuário aplica zoom ao mapa, os clusters se dividem em seus pontos de dados individuais. Quando você trabalha com um grande número de pontos de dados, os processos de clustering podem melhorar a experiência do usuário.

Habilitar o clustering na fonte de dados

Habilite o clustering na classe DataSource definindo a opção cluster como true. Defina clusterRadius para selecionar pontos próximos e combiná-los em um cluster. O valor de clusterRadius está em pixels. Use clusterMaxZoom para especificar um nível de ampliação para o qual deseja desabilitar a lógica de clustering. Aqui está um exemplo de como habilitar o clustering em uma fonte de dados.

//Create a data source and enable clustering.
var datasource = new atlas.source.DataSource(null, {
    //Tell the data source to cluster point data.
    cluster: true,
    
    //The radius in pixels to cluster points together.
    clusterRadius: 45,
    
    //The maximum zoom level in which clustering occurs.
    //If you zoom in more than this, all points are rendered as symbols.
    clusterMaxZoom: 15
});

Dica

Se dois pontos de dados estiverem próximos no solo, possivelmente o cluster nunca será dividido, independentemente de quanto o usuário ampliar. Para resolver isso, você pode definir a opção clusterMaxZoom para desabilitar a lógica de clustering e simplesmente exibir tudo.

A classe DataSource também fornece os seguintes métodos relacionados ao clustering.

Método	Tipo de retorno	Descrição
getClusterChildren(clusterId: number)	Promessa<Matriz<Recurso<Geometria, qualquer> | Forma>>	Recupera os filhos do cluster fornecido no próximo nível de zoom. Esses filhos podem ser uma combinação de formas e subclusters. Os subclusters são recursos com propriedades correspondentes a ClusteredProperties.
getClusterExpansionZoom(clusterId: number)	Promise<number>	Calcula um nível de zoom no qual o cluster começará a se expandir ou se separar.
getClusterLeaves(clusterId: number, limit: number, offset: number)	Promessa<Matriz<Recurso<Geometria, qualquer> | Forma>>	Recupera os pontos em um cluster. Por padrão, são retornados os primeiros 10 pontos. Para percorrer os pontos, use limit para especificar o número de pontos a serem retornados e offset para passar pelo índice de pontos. Para retornar todos os pontos, defina limit e Infinity não defina offset.

Exibir clusters usando uma camada de bolha

Uma camada de bolha é uma ótima maneira de renderizar os pontos clusterizados. Use as expressões para dimensionar o raio e alterar a cor com base no número de pontos no cluster. Se você exibir clusters usando uma camada de bolha, deverá usar uma camada separada para renderizar pontos de dados não clusterizados.

Para exibir o tamanho do cluster na parte superior da bolha, use uma camada de símbolo com texto e não use um ícone.

Para obter um exemplo de trabalho completo de como implementar a exibição de clusters usando uma camada de bolha, confira Clusters de pontos na camada de bolhas nos Exemplos do Azure Mapas. Para obter o código-fonte desse exemplo, consulte Código-fonte de Clusters de Pontos na Camada de Bolhas.

Exibir clusters usando uma camada de símbolo

Ao visualizar pontos de dados, a camada de símbolo oculta automaticamente os símbolos que se sobrepõem para garantir uma interface do usuário mais limpa. Esse comportamento padrão poderá ser indesejável se você quiser mostrar a densidade dos pontos de dados no mapa. No entanto, a maioria dessas configurações pode ser alterada. Para exibir todos os símbolos, defina a opção allowOverlap da propriedade iconOptions das camadas de Símbolo como true.

Use o clustering para mostrar a densidade dos pontos de dados enquanto mantém uma interface do usuário limpa. O exemplo a seguir mostra como adicionar símbolos personalizados e representar clusters e pontos de dados individuais usando a camada de símbolo.

Para obter um exemplo de trabalho completo de como implementar a exibição de clusters usando uma camada de símbolo, confira Exibir clusters com uma camada de símbolo nos Exemplos do Azure Mapas. Para obter o código-fonte desse exemplo, consulte Código-fonte do cluster de exibição com uma Camada de Símbolos.

Clustering e a camada de mapas de calor

Mapas de calor são uma ótima maneira de exibir a densidade dos dados no mapa. Esse método de visualização processa um grande número de pontos de dados por conta própria. Se os pontos de dados forem clusterizados e o tamanho do cluster for usado como o peso do mapa de calor, o mapa de calor poderá lidar com ainda mais dados. Para obter essa opção, defina a opção weight da camada do mapa de calor como ['get', 'point_count']. Quando o raio do cluster for pequeno, o mapa de calor será praticamente idêntico a um mapa de calor que usa os pontos de dados não clusterizados, mas ele terá um desempenho muito melhor. No entanto, quanto menor for o raio do cluster, mais preciso será o mapa de calor, mas com menos benefícios de desempenho.

Para obter um exemplo de trabalho completo que demonstra como criar um mapa de calor que usa clustering na fonte de dados, consulte Mapa de calor ponderado do cluster nos Exemplos do Azure Mapas. Para obter o código-fonte desse exemplo, consulte Código-fonte do Mapa de Calor ponderado por cluster.

Eventos de mouse em pontos de dados clusterizados

Quando ocorrem eventos de mouse em uma camada que contém pontos de dados clusterizados, o ponto de dados clusterizado retorna ao evento como um objeto de recurso de ponto do GeoJSON. O recurso de ponto tem as seguintes propriedades:

Nome da propriedade	Type	Descrição
cluster	booleano	Indica se o recurso representa um cluster.
cluster_id	string	Uma ID exclusiva para o cluster que pode ser usada com os métodos DataSource getClusterExpansionZoom, getClusterChildren e getClusterLeaves.
point_count	número	O número de pontos que o cluster contém.
point_count_abbreviated	string	Uma cadeia de caracteres que abreviará o valor point_count, se ele for longo. (por exemplo, 4.000 torna-se 4K)

O exemplo de Clusters de pontos na camada de bolhas usa uma camada de bolha que renderiza pontos de cluster e adiciona um evento de clique. Quando o evento de clique é disparado, o código calcula e amplia o mapa para o próximo nível de zoom, no qual o cluster se separa. Essa funcionalidade é implementada usando o método getClusterExpansionZoom da classe DataSource e a propriedade cluster_id do ponto de dados clusterizado clicado.

O snippet de código a seguir mostra o código no exemplo Clusters de pontos na camada de bolhas que adiciona a funcionalidade de evento de clique aos pontos de dados clusterizados:

//Add a click event to the layer so we can zoom in when a user clicks a cluster.
map.events.add('click', clusterBubbleLayer, clusterClicked);

//Add mouse events to change the mouse cursor when hovering over a cluster.
map.events.add('mouseenter', clusterBubbleLayer, function () {
    map.getCanvasContainer().style.cursor = 'pointer';
});

map.events.add('mouseleave', clusterBubbleLayer, function () {
    map.getCanvasContainer().style.cursor = 'grab';
});

function clusterClicked(e) {
    if (e && e.shapes && e.shapes.length > 0 && e.shapes[0].properties.cluster) {
        //Get the clustered point from the event.
        var cluster = e.shapes[0];

        //Get the cluster expansion zoom level. This is the zoom level at which the cluster starts to break apart.
        datasource.getClusterExpansionZoom(cluster.properties.cluster_id).then(function (zoom) {

            //Update the map camera to be centered over the cluster. 
            map.setCamera({
                center: cluster.geometry.coordinates,
                zoom: zoom,
                type: 'ease',
                duration: 200
            });
        });
    }
}

Exibir a área do cluster

Os dados de ponto que um cluster representa são distribuídos por uma área. Neste exemplo, ao passar o mouse sobre um cluster, ocorrem dois comportamentos principais. Primeiro, os pontos de dados individuais contidos no cluster são usados para calcular uma envoltória convexa. Em seguida, a envoltória convexa será exibida no mapa para mostrar uma área. Uma envoltória convexa é um polígono que encapsula um conjunto de pontos como uma banda elástica e pode ser calculada usando o método atlas.math.getConvexHull. Todos os pontos contidos em um cluster podem ser recuperados da fonte de dados usando o método getClusterLeaves.

Para obter um exemplo de trabalho completo que demonstra como fazer isso, confira Exibir área de cluster com envoltória convexa nos Exemplos do Azure Mapas. Para obter o código-fonte desse exemplo, consulte Exibir a área do cluster com o código-fonte do Envoltório Convexo.

Agregando dados em clusters

Geralmente, os clusters são representados usando um símbolo com o número de pontos que estão dentro do cluster. Mas, às vezes, é desejável personalizar o estilo dos clusters com métricas adicionais. Com as agregações de cluster, as propriedades personalizadas podem ser criadas e populadas usando um cálculo de expressão de agregação. As agregações de cluster podem ser definidas na opção clusterProperties do DataSource.

O exemplo de Agregações de cluster usa uma expressão de agregação. O código calcula uma contagem com base na propriedade de tipo de entidade de cada ponto de dados em um cluster. Quando um usuário seleciona um cluster, um pop-up é exibido com informações adicionais sobre o cluster. Para obter o código-fonte deste exemplo, consulte Código-fonte de agregação do cluster.

Próximas etapas

Saiba mais sobre as classes e métodos usados neste artigo:

Classe DataSource

Objeto DataSourceOptions

Namespace atlas.math

Consulte exemplos de código para adicionar funcionalidade ao seu aplicativo:

Adicionar uma camada de bolhas

Adicionar uma camada de símbolo

Adicionar uma camada do mapa de calor