Operações booleanas SVG no Paper.js: corte e una arte importada

Importe o SVG, encontre os objetos de traçado pretendidos e chame unite() para unir regiões preenchidas ou subtract() para remover uma região de outra. Mantenha os operandos até conferir o resultado e reabra o SVG exportado antes de usá-lo em outro lugar.

A decisão importante vem antes da operação booleana: quais formas devem ficar juntas? Um grupo importado pode conter retângulos de fundo, traçados de recorte, letras e partes decorativas. Combinar todos os filhos pode apagar as separações que você queria preservar. Este passo a passo usa três traçados fechados com nomes para que você veja exatamente o que muda.

Comece com geometria preenchida que você consiga identificar

O importador SVG do Paper.js aceita marcação SVG, um elemento SVG ou uma URL. Essas opções precisam de tratamentos diferentes de carregamento: este exemplo importa uma string inline; um arquivo remoto deve ser processado na função de retorno da importação após o carregamento.

Para esta tarefa, os operandos precisam ser objetos Path ou CompoundPath. Um grupo é um contêiner, e uma imagem raster não fornece o limite necessário para uma operação booleana de traçados. Se um arquivo se comporta apenas como uma única imagem, confira primeiro por que um SVG não pode ser desagrupado.

Use IDs para as partes que você controla. Não suponha que children[0] significa “o logo” em qualquer exportação. Inspecione artes desconhecidas e atribua as partes deliberadamente. Mantenha um traçado composto existente intacto quando seus subtraçados já definem os vazados pretendidos.

Execute uma pequena importação, união e subtração

Testamos o código abaixo com Paper.js 0.12.18 em um navegador. A arte é um SVG original feito manualmente: um corpo quadrado, uma aba sobreposta e um quadrado branco que marca a abertura pretendida. Não é uma amostra de conversão do PerfectVector.

Em uma pasta vazia, instale a biblioteca com versão fixada:

npm install --save-exact paper@0.12.18

Salve isto como index.html:

<!doctype html>
<meta charset="utf-8">
<title>SVG Boolean example</title>
<canvas id="work" width="300" height="220" hidden></canvas>
<div id="result" style="background:#d8e8e0; width:300px"></div>
<pre id="svg-output"></pre>
<script src="node_modules/paper/dist/paper-full.min.js"></script>
<script src="example.js"></script>

Salve isto como example.js e abra o HTML em um navegador:

paper.setup(document.getElementById('work'));
const source = `<svg xmlns="http://www.w3.org/2000/svg" width="300" height="220" viewBox="0 0 300 220">
  <path id="body" fill="#176b62" d="M40 40H180V180H40Z"/>
  <path id="tab" fill="#ee9852" d="M160 80H260V140H160Z"/>
  <path id="hole" fill="#ffffff" d="M80 80H130V130H80Z"/>
</svg>`;
const imported = paper.project.importSVG(source, { insert: false, expandShapes: true });
function operand(name) {
  const item = imported.getItem({ name });
  if (!(item instanceof paper.Path || item instanceof paper.CompoundPath)) {
    throw new Error(`Expected path geometry for ${name}`);
  }
  return item;
}
const joined = operand('body').unite(operand('tab'), { insert: false });
const cut = joined.subtract(operand('hole'), { insert: false });
cut.fillColor = '#176b62';
cut.strokeColor = null;
paper.project.activeLayer.addChild(cut);
const output = paper.project.exportSVG({ asString: true, bounds: new paper.Rectangle(0, 0, 300, 220) });
document.getElementById('result').innerHTML = output;
document.getElementById('svg-output').textContent = output;

A importação fica fora da cena com insert: false. expandShapes: true solicita ao importador que transforme formas primitivas compatíveis em traçados; nosso exemplo já contém elementos path. A verificação explícita de classe ainda importa, pois um ID importado pode identificar um contêiner ou outro tipo de item.

A API booleana retorna um novo item de traçado. Aqui, o resultado é mantido fora da cena até a forma final recortada ser adicionada. As partes originais continuam disponíveis em imported, portanto uma operação que falha não exige reconstruir a arte original.

joined.subtract(hole) remove o vazado da silhueta unida. Inverter os operandos faz outra pergunta e pode produzir um resultado vazio ou inesperado. O modo padrão de subtração do Paper.js trata os operandos como áreas. Sua opção trace se refere à geometria booleana; não tem relação com vetorizar um PNG.

Confira o resultado como geometria e como arquivo

Neste exemplo, a união retornou um Path; a subtração retornou um CompoundPath com dois contornos. Os limites finais foram x = 40, y = 40, largura = 220 e altura = 140 em unidades SVG. A arte fica dentro de uma área de visualização de exportação de 300 × 220, portanto os limites e o tamanho do documento são intencionalmente diferentes.

Conferimos o centro da abertura em (105, 105): ele estava dentro da silhueta unida e fora do resultado subtraído. Um ponto no corpo sólido em (60, 60) permaneceu dentro. Reimportar o SVG exportado preservou os limites e voltou a excluir o centro do vazado. Esses são resultados deste exemplo simples de teste, não uma garantia para todos os arquivos importados.

A API de exportação pode retornar uma string SVG e receber limites explícitos. Copie a marcação exibida abaixo do resultado para result.svg e abra esse arquivo de forma independente. Nossa exportação salva continha um elemento path com dois subtraçados fechados; ela também foi renderizada corretamente ao ser aberta diretamente no navegador.

Para sua arte, confira:

• a silhueta e cada abertura em relação ao original;
• se algum fundo ou alguma forma auxiliar oculta foi incluída por acidente;
• o preenchimento pretendido, pois uma forma unida não consegue preservar dois preenchimentos chapados editáveis de forma independente;
• a área de visualização exportada, especialmente quando a arte chega à borda do documento;
• o arquivo no aplicativo que realmente o usará.

Uma sobreposição branca pode parecer uma abertura em papel branco. Coloque o resultado sobre um fundo contrastante para conferir a transparência. O guia de vazados SVG preenchidos explica os problemas relacionados a traçados compostos e regras de preenchimento.

Quando a operação produz a forma errada

Um método está ausente. Inspecione a classe do item selecionado. Encontre o traçado pretendido dentro de um grupo ou converta formas primitivas compatíveis durante a importação. Não resolva isso combinando todos os descendentes: traçados compostos também contêm filhos, e as relações de seus vazados importam.

O resultado parece inalterado. Certifique-se de exibir o item retornado. Deixar os originais visíveis pode encobrir uma subtração bem-sucedida. No exemplo, somente o resultado final entra na camada ativa.

Um contorno desaparece ou muda de significado. Este exemplo opera em regiões fechadas e preenchidas. Uma linha grossa visível não é automaticamente a mesma forma que a área coberta por seu contorno. Se você precisa dessa borda como operando preenchido, prepare uma cópia com o contorno convertido em forma em um editor vetorial e inspecione-a antes de importar. Mantenha o original editável.

Uma arte detalhada se comporta mal. Isole dois operandos e inspecione seus contornos antes de aplicar uma sequência a uma ilustração inteira. Duplicatas, autointerseções e fragmentos minúsculos precisam de verificações específicas para cada caso. Este pequeno exemplo não mede desempenho nem compatibilidade ampla com SVG. Para um reparo pontual, as ferramentas de seleção e nós de um editor vetorial podem ser mais fáceis do que escrever um fluxo de processamento de geometria.

Quando sua imagem original ainda é um PNG ou JPG

Se o original editável está ausente, o fluxo de imagem para vetor do PerfectVector pode ajudar a preparar um SVG a partir de uma arte raster adequada. Visualize o resultado, inspecione os contornos e espaços negativos e baixe uma versão candidata para testar no Paper.js.

A vetorização não identifica quais partes seu programa deve unir ou subtrair. Você ainda precisa inspecionar a estrutura importada, selecionar os operandos certos e conferir o resultado exportado. Use o vetor original quando você o tiver; desenhe diretamente um quadrado ou círculo simples em vez de vetorizá-lo. A visão geral de vetorização de imagens aborda essa decisão sobre o arquivo de origem.

Perguntas frequentes

Posso chamar unite em um grupo SVG importado? Selecione primeiro os operandos Path ou CompoundPath pretendidos dentro do grupo. Um grupo descreve organização, e combinar todos os filhos pode incluir fundos ou destruir separações intencionais.

subtract remove os traçados originais? Ele retorna um novo item de traçado. Este exemplo usa insert: false para a importação e os resultados booleanos e insere apenas o resultado final. Os operandos de origem continuam disponíveis no contêiner importado.

Por que um vazado ainda parece branco? Confira-o contra um fundo colorido. Um objeto com preenchimento branco cobre o que está atrás; uma abertura subtraída revela esse fundo. Reabra o arquivo exportado para confirmar que a relação é preservada.

A vetorização fará a limpeza booleana por mim? Não. Ela pode recuperar arte em traçados a partir de uma imagem raster adequada, mas seu aplicativo ainda precisa escolher qual geometria unir, qual área remover e como validar o resultado.

Fontes

1. Paper.js — referência de Project — Documenta importação e exportação SVG, limites e conteúdo do projeto.
2. Paper.js — referência de Path — Define união e subtração, os itens de traçado retornados e as opções booleanas.
3. Paper.js — referência de CompoundPath — Descreve a geometria composta e seus traçados constituintes.

Se uma imagem raster é seu único material de origem, prepare uma versão candidata em SVG, inspecione suas partes e teste a menor operação booleana útil antes de processar o restante da arte.