Extraia a paleta de cores dominantes de uma imagem

Transforme uma lista representativa de pixels da imagem em uma paleta de cores compacta e útil. Este recurso agrupa valores RGB próximos, classifica os grupos por presença ponderada e apresenta cada cor dominante como amostra hexadecimal e canais RGB, junto com sua contagem de pixels e participação na amostra fornecida. Ele foi criado para fluxos que já amostraram ou contaram pixels e precisam de um resumo determinístico sem enviar nem decodificar a imagem original.

Prepare amostras representativas de pixels

Comece com pixels coletados em toda a imagem, e não apenas em um canto conveniente. Cada registro contém valores dos canais vermelho, verde e azul entre 0 e 255. Se o pré-processamento já contou cores idênticas, adicione count ao registro; caso contrário, omita esse campo e cada registro representará um pixel.

Registros ponderados são particularmente úteis em imagens com grandes áreas uniformes, pois preservam a frequência real sem exigir a repetição do mesmo objeto RGB milhares de vezes. A amostragem deve ser equilibrada no espaço. Uma grade simples, um intervalo uniforme ou uma prévia reduzida geralmente retrata melhor a imagem do que os primeiros pixels na ordem do arquivo.

Exclua pixels transparentes, a menos que eles já tenham sido compostos sobre o fundo que ficará visível, pois um valor RGB invisível não deve definir uma paleta visível. O algoritmo reúne duplicatas exatas antes do agrupamento; portanto, registros repetidos e um registro equivalente com contagem produzem o mesmo resultado.

Entenda o agrupamento determinístico de cores

Escolha n como o número máximo de cores dominantes desejadas. Ele deve ser um inteiro de pelo menos 1, e o recurso devolve menos cores quando a amostra contém menos valores RGB distintos. Os centros são inicializados de modo determinístico a partir de amostras frequentes e bem separadas, depois refinados por um agrupamento ponderado e limitado no espaço RGB.

Não há semente aleatória, relógio, serviço de rede ou modelo; assim, entradas idênticas produzem saídas idênticas. Tons próximos podem entrar no mesmo grupo, permitindo que artefatos de compressão, antisserrilhamento, gradientes e pequenas variações de luz contribuam para uma amostra representativa, em vez de fragmentar a resposta. O valor RGB representativo é a média ponderada do grupo, arredondada para canais inteiros válidos, e o hexadecimal deriva dos mesmos canais.

Os grupos são classificados por contagem de pixels, com desempate hexadecimal estável. A distância RGB é simples e previsível de propósito: trata-se de um resumo prático, não de um sistema perceptual para impressão crítica.

Aproveite contagens e proporções no fluxo

A resposta contém um array colors ordenado da maior contagem de pixels representados para a menor. Cada item inclui hex, um objeto RGB, count e share. Use a primeira cor como aproximação do destaque dominante, mas confira sua proporção antes de concluir que ela representa a maior parte da imagem.

Uma cor líder com participação próxima da metade é um sinal visual muito mais forte do que a primeira cor de uma paleta equilibrada com cinco tons. Para automação, armazene toda a lista classificada, permitindo ajustar limites sem processar as amostras novamente. Canais inválidos, registros malformados e n abaixo de 1 geram erros explícitos.