Escala de mapa por medição

Distâncias nulas ou negativas são rejeitadas com um erro invalid_input claro em vez de inventar uma escala impossível. O caminho é matemática pura e determinística—sem rede, sem sementes aleatórias, sem dependência de relógio—de modo que o executor gratuito do navegador e a API pré-paga devolvem o mesmo JSON após o arredondamento decimal fixo sempre que você a chama.

Como a escala de fração representativa se define a partir de dois comprimentos medidos

Quando você já conhece ambos os comprimentos—por exemplo dois centímetros no papel abrangendo um quilômetro no campo—converte ambas as medições para um único sistema de unidades e forma N igual a ground_length dividido por map_length. A resposta ecoa o map_distance e o ground_distance arredondados que você enviou, registra map_unit e ground_unit, publica map_distance_m e ground_distance_m, expõe scale_denominator e scale_denominator_raw, scale_ratio como a string 1:N, representative_fraction como 1/N, precision, a etiqueta de método map_scale_from_measure, formula como a string N equals ground_m over map_m, message como um resumo breve em inglês do motor e steps como um registro de substituição ordenado. O motor divide dois comprimentos em metros positivos e finitos dentro da faixa de magnitude suportada ou rejeita a entrada com invalid_input. Os casos rejeitados incluem map_distance ou ground_distance ausentes, valores não finitos, magnitudes fora do teto publicado, tokens de unidade fora do enum e qualquer distância nula ou negativa, porque um comprimento geométrico não positivo não pode definir uma escala de razão.

Contrato de entrada, forma da resposta e comportamento de erro

Em caso de sucesso a resposta inclui os comprimentos convertidos para metros, os campos de escala listados acima, formula e message, e steps como o registro de substituição que você pode afirmar em testes ou mostrar ao lado de um croqui. Prefira enviar números em vez de strings pré-formatadas quando controlar o cliente; quando precisar enviar strings, coloque as unidades apenas nos campos de unidade, não coladas aos valores de distância. Envie um corpo JSON com dois campos obrigatórios: map_distance para o comprimento medido no mapa (aliases map_dist, map, measured_map, d_map) e ground_distance para o comprimento real correspondente (aliases ground_dist, ground, real_distance, d_ground, true_distance). Ambos devem ser finitos e estritamente positivos dentro da faixa absoluta publicada para que as conversões intermediárias para metros e a razão permaneçam doubles IEEE finitos e positivos. O map_unit opcional tem padrão centímetros e ground_unit tem padrão quilômetros—o emparelhamento usual de mapa em papel e barra de escala—e cada um aceita o enum fechado mm, cm, m, km, in, ft, yd, mi para que o renderizador do formulário ofereça um controle select em vez de texto livre. O precision opcional (aliases decimals, dp) escolhe quantas casas decimais expor para campos numéricos não inteiros, com padrão doze e teto quinze para que os goldens JSON permaneçam estáveis entre runtimes; quando o denominador absoluto é pelo menos um ele é arredondado para inteiro na apresentação convencional de RF enquanto scale_denominator_raw preserva o quociente sem arredondamento. Formas em string de números são aceitas quando coincidem com um padrão decimal finito estrito com notação científica opcional; espaços embutidos, sufixos de unidade dentro dos campos numéricos e tokens não numéricos falham com uma mensagem invalid_input clara que nomeia o campo. A validação falha—campos ausentes, números não finitos, distâncias nulas ou negativas, unidades desconhecidas ou valores fora dos limites absolutos—devolve invalid_input e nunca é cobrada. O preço é um valor fixo US$ 0,002 por pedido bem-sucedido com unidade item.

Onde a escala de mapa por medição se encaixa em campo, estudo e software

Nesta página o trabalho roda inteiramente no seu navegador; pela API cada consulta bem-sucedida custa US$ 0,002, a validação falha não é cobrada e nada é armazenado após a resposta retornar. Essa divisão—exploração interativa gratuita e uma API idêntica cobrada—corresponde ao restante do catálogo KIT de nível A e permite passar de uma demonstração em sala para um pipeline automatizado sem alterar o resultado matemático.