Unidades de clipPath em SVG: ajuste uma forma ao alvo

Use clipPathUnits="objectBoundingBox" quando uma forma de recorte deve se esticar com os limites do alvo. Normalize primeiro as coordenadas da forma. Use userSpaceOnUse quando precisar de posicionamento explícito ou de uma escala uniforme que preserve as proporções da forma.

Alterar apenas o atributo não converte um traçado desenhado em centenas de unidades em uma forma entre zero e um. Isso pode deslocar quase todo o recorte para fora do alvo. Este guia usa uma silhueta original de marcador de página para mostrar a mudança de coordenadas, a distorção resultante e um ajuste centralizado que mantém quadrada a abertura em losango.

O recorte controla a visibilidade. Ele não apara os traçados subjacentes para criar uma nova geometria editável. Se você já tem uma silhueta SVG limpa, use-a diretamente; a vetorização só é relevante quando você precisa recuperar essa silhueta de uma imagem raster.

Escolha o sistema de coordenadas antes de redimensionar

O padrão é userSpaceOnUse. Suas coordenadas de recorte pertencem ao sistema de coordenadas do usuário do elemento que referencia o recorte. Com objectBoundingBox, o limite superior esquerdo do alvo corresponde a (0, 0) e o limite inferior direito corresponde a (1, 1). Consulte a referência de clipPathUnits.

A caixa delimitadora do alvo não é necessariamente o viewBox do SVG externo. Recortar um grupo usa os limites desse grupo, que podem ser diferentes dos de um retângulo dentro dele. Para um primeiro teste previsível, aplique o recorte diretamente a um retângulo de dimensões conhecidas.

Compare um alvo largo com um alto

Os limites externos do nosso marcador de página são x=20, y=10, width=100, height=100. Seu losango é um segundo subtraçado dentro do mesmo traçado. O teste o aplica a retângulos de 200 × 120 e 120 × 200 em unidades locais do SVG.

A coluna do meio preenche os limites de cada alvo, mas seu losango fica largo ou alto. A coluna da direita preserva o losango e o entalhe inferior, deixando espaço no eixo mais longo do alvo. Todas as seis aberturas continuam transparentes.

Salve o exemplo completo abaixo como clippath-comparison.svg e abra-o em um navegador. As colunas seguem a ordem da imagem. A linha superior usa retângulos largos; a inferior usa retângulos altos. As translações de exibição organizam as amostras e não alteram as dimensões locais de seus alvos.

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 470">
  <defs>
    <path id="silhouette" d="M20 10H120V110L70 85L20 110Z M70 30L85 45L70 60L55 45Z"/>
    <clipPath id="fixed" clipPathUnits="userSpaceOnUse">
      <use href="#silhouette" clip-rule="evenodd"/>
    </clipPath>
    <clipPath id="box" clipPathUnits="objectBoundingBox">
      <use href="#silhouette" clip-rule="evenodd"
        transform="matrix(.01 0 0 .01 -.2 -.1)"/>
    </clipPath>
    <clipPath id="wide-fit" clipPathUnits="userSpaceOnUse">
      <use href="#silhouette" clip-rule="evenodd"
        transform="matrix(1.2 0 0 1.2 16 -12)"/>
    </clipPath>
    <clipPath id="tall-fit" clipPathUnits="userSpaceOnUse">
      <use href="#silhouette" clip-rule="evenodd"
        transform="matrix(1.2 0 0 1.2 -24 28)"/>
    </clipPath>
  </defs>
  <g fill="#107c86">
    <rect x="0" y="0" width="200" height="120"
      transform="translate(20 30)" clip-path="url(#fixed)"/>
    <rect x="0" y="0" width="200" height="120"
      transform="translate(260 30)" clip-path="url(#box)"/>
    <rect x="0" y="0" width="200" height="120"
      transform="translate(500 30)" clip-path="url(#wide-fit)"/>
    <rect x="0" y="0" width="120" height="200"
      transform="translate(60 230)" clip-path="url(#fixed)"/>
    <rect x="0" y="0" width="120" height="200"
      transform="translate(300 230)" clip-path="url(#box)"/>
    <rect x="0" y="0" width="120" height="200"
      transform="translate(540 230)" clip-path="url(#tall-fit)"/>
  </g>
</svg>

A pintura verde-azulada pertence aos retângulos. O traçado de recorte fornece seu contorno visível. A captura de tela acrescenta rótulos e um quadriculado ao redor desse mesmo SVG; o arquivo independente tem fundo transparente.

Normalize os limites da arte original, incluindo sua origem

Para um ponto (x, y) na arte original cujos limites são (minX, minY, width, height), calcule:

normalizedX = (x - minX) / width
normalizedY = (y - minY) / height

Aqui, isso corresponde a (x - 20) / 100 e (y - 10) / 100. A matriz na definição box executa as duas operações sem reescrever os dados do traçado:

matrix(0.01 0 0 0.01 -0.2 -0.1)

Ela mapeia (20, 10) para (0, 0) e (120, 110) para (1, 1). Dividir por 100 sem subtrair a origem deixaria a forma deslocada dentro do alvo. O mapeamento pela caixa delimitadora escala então o resultado normalizado de maneira independente na largura e na altura do alvo.

Use os limites reais da geometria que você quer normalizar. Um viewBox pode incluir espaços vazios intencionais, portanto suas dimensões não precisam ser iguais aos limites da silhueta. Se quiser manter esse espaço, use deliberadamente o retângulo do viewBox, em vez de misturar as duas medidas por acidente.

Para uma arte importada com transformações aninhadas, meça e normalize em um único sistema de coordenadas consistente. Resolva essas transformações em um editor antes de copiar os dados brutos do traçado se você não conseguir levá-las em conta com segurança. O fluxo de edição de SVG aborda a inspeção de traçados e grupos antes da entrega.

Preserve as proporções com um único fator de escala

Para um retângulo de destino na posição local (0, 0), com largura W e altura H, use:

s  = min(W / width, H / height)
tx = (W - s * width) / 2 - s * minX
ty = (H - s * height) / 2 - s * minY
matrix(s 0 0 s tx ty)

O alvo largo resulta em s=1.2, tx=16 e ty=-12. Seu recorte ocupa x=40..160 e y=0..120. O alvo alto resulta em s=1.2, tx=-24 e ty=28, posicionando o recorte em x=0..120 e y=40..160.

Essas são matrizes explícitas em userSpaceOnUse, portanto recalcule-as quando as dimensões locais do alvo mudarem. Apenas exibir o SVG inteiro em outro tamanho CSS escala toda a composição em conjunto. Alterar um retângulo dentro dele de largo para alto é uma operação diferente.

Esse cálculo pressupõe largura e altura da arte original diferentes de zero e nenhuma rotação ou inclinação não considerada. É uma operação de ajuste dentro dos limites: deixar espaço é esperado. Esticar com unidades da caixa delimitadora é adequado quando preencher o alvo importa mais do que preservar as proporções do motivo.

Mantenha a abertura na geometria de recorte

O exemplo coloca clip-rule="evenodd" em cada use dentro de seu clipPath. O traçado referenciado contém tanto o marcador externo quanto o subtraçado do losango. A regra determina quais regiões dessa forma composta ficam dentro do recorte.

Colocar clip-rule no retângulo verde-azulado não define a regra da forma de recorte. Da mesma maneira, um fill-rule usado para pintar a arte original não substitui a regra de recorte. A referência de clip-rule da MDN explica seu escopo dentro de um clipPath.

Não acrescente um losango branco separado esperando que ele seja subtraído do recorte. As silhuetas filhas em um traçado de recorte são combinadas em uma região visível; suas cores de pintura não funcionam como valores de máscara em preto e branco. Para um vazado como esse, use o traçado composto e a regra de orientação pretendida. O guia de vazados preenchidos em SVG explica a estrutura subjacente do traçado.

Se seu desenho precisa de bordas parcialmente transparentes ou visibilidade baseada em luminância, compare um clipPath e uma máscara SVG na mesma imagem. Um recorte é útil para um limite geométrico; uma máscara oferece outro modelo de visibilidade. Para um ícone de uma só cor pintado por CSS, consulte o guia de máscaras SVG em CSS.

Confira os limites e o resultado exportado

Uma linha horizontal ou vertical pode ter uma caixa delimitadora geométrica de altura ou largura zero mesmo quando seu contorno é visível. Evite objectBoundingBox para esses alvos e não divida por uma dimensão da arte original igual a zero ao normalizar. A especificação de coordenadas SVG exclui a largura do contorno desse cálculo da caixa delimitadora e alerta sobre esses casos degenerados.

Antes da entrega:

1. Confirme que o ID do recorte referenciado existe e é único no documento.
2. Compare alvos largos e altos, incluindo a menor abertura.
3. Confira os limites da arte original e do alvo nos sistemas de coordenadas pretendidos.
4. Salve e reabra o SVG exportado no aplicativo que vai consumi-lo.
5. Mantenha a geometria original quando o recorte precisar continuar editável.

A especificação CSS Masking afirma que o recorte muda a renderização, não a geometria inerente do elemento. Uma máquina de corte ou um aplicativo que processa geometria pode, portanto, precisar de uma interseção real de traçados ou de outra operação no editor. Confirme os traçados resultantes nesse aplicativo; uma prévia correta no navegador, sozinha, não comprova que o arquivo está pronto para corte.

Recupere uma silhueta raster quando necessário

O PerfectVector é adequado quando um motivo personalizado existe apenas como PNG ou JPG e você precisa de contornos editáveis para o recorte. Converta essa imagem para SVG e inspecione a borda externa, as aberturas internas e quaisquer formas de fundo indesejadas antes de extrair a silhueta. Escolha quais contornos pertencem ao recorte; as cores da imagem original não definem intensidades de recorte separadas.

Mantenha um arquivo mestre vetorial existente se você tiver um. Um marcador de página geométrico simples pode ser desenhado diretamente, como neste exemplo. A vetorização não escolhe as unidades do recorte, não normaliza os limites nem realiza um corte booleano permanente. Para orientações mais amplas sobre a escolha da imagem original, leia a visão geral de vetorização de imagens.

Perguntas frequentes

objectBoundingBox preserva as proporções da forma? Não. Ele mapeia o recorte normalizado para a largura e a altura do alvo de maneira independente. Use uma escala uniforme em userSpaceOnUse quando a silhueta precisar manter suas proporções.

Por que alterar clipPathUnits esconde minha forma? As coordenadas do traçado podem ainda estar nas unidades da arte original. Normalize-as para o sistema de coordenadas relativo ao alvo, incluindo a origem da forma, ou mantenha userSpaceOnUse e posicione-as explicitamente.

O recorte exclui as partes ocultas do meu SVG? Não. O recorte muda o que é renderizado e mantém a geometria subjacente. Use uma operação adequada de edição de traçados se o arquivo entregue precisar de contornos aparados permanentemente.

Fontes

1. MDN — clipPathUnits — Opções de coordenadas e interpretação padrão do espaço do usuário.
2. MDN — clip-rule — Posicionamento da regra de orientação dentro de traçados de recorte.
3. W3C — sistemas de coordenadas SVG — Mapeamento pela caixa delimitadora, exclusão do contorno e limitações de dimensões zero.
4. W3C — CSS Masking — Geometria de recorte, silhuetas combinadas e traçados subjacentes inalterados.

Se seu recorte começa com um motivo raster, prepare seu SVG com o PerfectVector, inspecione a silhueta e as aberturas e teste as duas proporções do alvo antes de escolher entre esticar ou ajustar uniformemente.