Quantize uma cor para o tom mais próximo da paleta

Quantize uma cor em uma paleta fixa quando uma imagem indexada, um tema de terminal, um controlador LED, um conjunto de tokens de design ou um formato de exportação restrito aceitar apenas cores aprovadas. Informe uma cor hexadecimal de origem e uma paleta ordenada. O recurso valida todos os valores, compara distâncias RGB exatas e retorna a cor normalizada mais próxima, seu índice iniciado em zero e a distância ao quadrado. Em caso de empate, a primeira entrada sempre é escolhida, portanto execuções repetidas produzem a mesma saída.

Prepare uma paleta fixa com intenção

A quantização de cores começa pelas tonalidades que o destino realmente pode armazenar ou exibir. Coloque essas cores no array da paleta em uma ordem estável e deliberada, usando a notação #RGB ou #RRGGBB. As formas curtas são expandidas antes da comparação, e letras maiúsculas ou minúsculas não alteram o resultado.

A cor de origem segue a mesma notação. Uma paleta pode conter de uma a 256 entradas, o que atende a pequenos conjuntos de marca, cores de terminal, tabelas clássicas de imagens indexadas, seleções de linhas de bordado e vários mapas de cores específicos de dispositivos. A ordem só importa quando duas entradas estão à mesma distância da origem.

Nesse caso, vence a primeira. Essa regra explícita torna os empates previsíveis e permite indicar preferência sem alterar as cores. Mantenha a paleta fixa em todo o lote quando precisar de uma saída indexada consistente.

Se trabalhos diferentes reordenarem a paleta silenciosamente, o índice retornado poderá mudar mesmo que a cor escolhida continue igual. O validador rejeita arrays vazios ou grandes demais, prefixos ausentes, canais alfa, dígitos inválidos e entradas que não sejam strings, sem tentar adivinhar a intenção.

Entenda o cálculo determinístico da distância

Cada cor aceita é expandida para seis dígitos hexadecimais e convertida em valores dos canais vermelho, verde e azul entre 0 e 255. O algoritmo subtrai cada canal da paleta do canal correspondente da origem, eleva as três diferenças ao quadrado e soma os resultados. A entrada da paleta com o menor total é selecionada.

Trata-se da distância euclidiana comum no espaço RGB codificado, escolhida para uma conversão indexada transparente e reproduzível, não para representar a percepção humana. A comparação só troca o candidato quando encontra um valor estritamente menor; assim, uma distância igual nunca substitui uma opção anterior. Esse detalhe garante desempate determinístico até em paletas simétricas ou com itens duplicados.