Recortar imagem em caixa

Este validador recebe a largura e a altura da imagem de origem, além de uma caixa definida por x, y, largura e altura. Ele verifica cada valor, confirma que o retângulo inteiro permanece dentro da imagem e retorna as dimensões recortadas quando a caixa é válida. Nenhum upload ou decodificação é necessário, por isso a ferramenta é útil antes de acionar um processador de imagens, montar uma prévia de corte ou aceitar coordenadas vindas de outro serviço.

Descreva a imagem de origem e a caixa

Comece pelas dimensões em pixels da imagem original. Informe em image_width a contagem horizontal total de pixels e em image_height a contagem vertical total. Em seguida, descreva o retângulo com x, y, width e height. Os valores x e y posicionam o canto superior esquerdo da caixa em relação ao canto superior esquerdo da imagem, cuja coordenada é 0,0. Width avança para a direita e height para baixo. Os seis valores precisam ser inteiros, pois a capacidade representa cortes rasterizados alinhados aos pixels, e não geometria fracionária. As dimensões da imagem e do corte devem ser positivas; x e y podem ser zero. Por exemplo, x igual a 240 ignora as primeiras 240 colunas de pixels. A caixa pode encostar exatamente em qualquer borda. Portanto, x mais width pode ser igual a image_width, e y mais height pode ser igual a image_height. Use as dimensões do mesmo arquivo que será recortado; coordenadas de uma prévia redimensionada precisam ser escaladas antes.

Entenda como os limites são validados

O validador primeiro rejeita valores ausentes, números não inteiros, coordenadas negativas, caixas sem área e valores fora do intervalo documentado. Depois verifica as duas fronteiras que determinam a contenção. Na horizontal, x mais width deve ser menor ou igual a image_width. Na vertical, y mais height deve ser menor ou igual a image_height. Se alguma soma for maior, uma parte do corte estará fora da origem e a solicitação retornará um erro de entrada inválida. Essa regra explícita evita uma confusão comum de uma unidade: um corte com largura de 100 pixels iniciado em x 0 ocupa toda uma extensão de 100 pixels e cabe exatamente em uma imagem de 100 pixels. A capacidade não limita, desloca nem reduz uma caixa inválida, porque alterar coordenadas silenciosamente pode selecionar outro assunto ou composição. Ela também não examina os bytes da imagem. A decisão depende apenas das dimensões e coordenadas fornecidas, o que produz uma validação rápida, repetível e adequada tanto a formulários interativos quanto a pipelines automatizados.

Use o resultado antes de recortar de fato

Uma resposta bem-sucedida retorna a largura e a altura do corte resultante. Esses valores coincidem com a caixa solicitada porque esta capacidade valida geometria; ela não redimensiona nem altera o retângulo. Use a resposta como proteção antes de enviar as mesmas coordenadas a uma biblioteca gráfica, um serviço de mídia ou uma tarefa de renderização em fila. Assim, você separa a validação barata da decodificação mais cara e impede que falhas previsíveis cheguem aos processos seguintes. Em um editor, valide após a confirmação da seleção ou depois de converter as coordenadas da prévia em pixels da imagem original. Em um pipeline, confira os metadados assim que chegarem e encaminhe registros inválidos para correção. Considere a orientação: se outra etapa girar fisicamente a imagem, use as dimensões posteriores à rotação e coordenadas na mesma orientação. A solicitação à API custa US$ 0,002; o executor do navegador realiza localmente o mesmo cálculo determinístico. Nenhum dos caminhos envia a imagem, pois somente a geometria numérica é necessária.