Pixerate/pixerate-vector

Editor vetorial Pixerate

O documento vetorial é uma prancheta (largura x altura em unidades do documento, y para baixo) que contém uma árvore de nós: nós path (um ou mais subcaminhos de âncoras Bezier, com preenchimento, traçado e configurações de traçado), nós text (uma string definida como texto de ponto, texto de área ou ao longo de um caminho, pintada com os mesmos preenchimentos e traçados), nós instance (uma cópia colocada de um símbolo) e nós group. Grupos também podem ser booleanos ao vivo, mesclagens ao vivo, grupos de máscara ou carregar uma pilha de efeitos ao vivo. Todo comando é um comando vector.* executado com run_command / run_commands (veja pixerate-agent-tools para agrupamento com referências "$0.id", atomic: true e códigos de erro).

• IDs de nós vêm de vector.list e do que as escritas retornam ({ id }, { ids }).
• Âncoras são { nodeId, subpath, index }: número do subcaminho dentro do caminho, depois número da âncora dentro do subcaminho, ambos a partir de 0. Comandos que usam anchors usam por padrão os pontos selecionados com a ferramenta direta; aqueles que usam ids usam a seleção por padrão.
• Paint é uma cor CSS, null para nenhum, ou um objeto gradiente { type, stops: [{ offset, color, opacity?, midpoint? }], ... }.
• Aparência: um caminho pode empilhar vários preenchimentos e vários traçados (de baixo para cima; todos os preenchimentos desenham sob todos os traçados), cada um com seu próprio paint, opacity, blendMode e visible, e cada traçado com sua própria largura, alinhamento, tracejados, pontas, uniões, pontas de seta e perfil, ou uma pincelada (vector.addBrushstroke, vector.setBrushstroke, vector.listBrushes) pintada ao longo do contorno com um pincel seco ou úmido, um Mixer Brush, smudge ou blender, tinta gradiente, jitter semeado e grão de papel. As camadas são endereçadas por index em sua pilha, 0 na parte inferior. fill / stroke e as configurações de traçado de vector.setStyle são atalhos para a camada superior; null limpa a pilha. Qualquer nó também pode ter um blendMode e filters (sombra projetada/interna, brilho externo/interno, desfoque de camada, pena), que nunca alteram a geometria.
• Máscaras: o primeiro filho (inferior) de um grupo de máscara é sua máscara; os filhos acima dele aparecem apenas dentro do contorno da máscara (clip), ou onde ela é brilhante (luminance) ou opaca (alpha). invert troca o que é mostrado e o que é ocultado. vector.list dá a um grupo de máscara uma mask { type, invert, maskId, contents, enabled }; uma máscara oculta (enabled: false) não mascara nada.
• Texto tem uma font base (família, peso, itálico, tamanho, tracking, entrelinha, deslocamento de linha de base, sublinhado, tachado), execuções opcionais que substituem campos em intervalos (start / end em unidades de código UTF-16, mais um fill de intervalo), um estilo paragraph e um frame: point (x, y da primeira linha de base), area (uma caixa na qual ele se ajusta) ou path (uma linha que ele segue).
• Símbolos são arte reutilizável mantida com o documento (vector.listSymbols), desenhados por nós instance através de uma transformação que, ao contrário de outros nós, pode escalar e distorcer. Editar um símbolo (vector.editSymbol … vector.exitSymbolEdit) altera todas as instâncias.
• Restrições (estilo CAD) mantêm relações geométricas e dimensões entre âncoras, segmentos e caminhos redondos; elas são resolvidas após cada edição, para que movimentos posteriores as mantenham.
• Quadros são grupos com um retângulo frame (vector.listFrames): eles desenham um fundo, recortam seus filhos e selecionam pelo seu retângulo; quadros de nível superior são pranchetas. Quando um quadro é redimensionado, seus filhos seguem suas restrições de redimensionamento (horizontal left / right / leftRight / center / scale, vertical top / bottom / topBottom / center / scale) em vez de escalar.
• Conectores são caminhos abertos com um connector cujas extremidades são coladas a locais de outros objetos (o meio de um lado, ou o centro); eles são roteados novamente após cada edição, de modo que seguem o que conectam. Uma extremidade livre permanece onde está.
• Grupos de simetria desenham seus filhos mais cópias espelhadas ou rotacionadas. Adicione arte a um com parentId em vector.addShape / vector.addPath; apenas os originais são armazenados e editados.
• As coordenadas estão em unidades do documento. Um nó rotacionado armazena sua geometria em seu próprio espaço: os bounds que vector.list relata são no espaço do documento, seu d é o próprio do nó.

Detalhes dos parâmetros (campos de gradiente, parâmetros de efeito, perfis de largura, envelopes) estão em references/commands.md.

Skills de fluxo de trabalho

Para esses trabalhos, carregue a skill de fluxo de trabalho também: ela tem o método, as verificações entre etapas e as armadilhas, e usa os comandos abaixo.

• pixerate-vector-icon-set: ícones em uma grade, um traçado e estilo, nítidos, como símbolos e SVG.
• pixerate-vector-logo: marcas a partir de booleanos, um lockup, variantes de cor, arquivos de entrega delineados.
• pixerate-vector-illustration: bloco inicial, gradientes e preenchimentos empilhados, máscaras, mesclagens, sombras.

Método de trabalho

1. Leia. vector.list fornece o tamanho da prancheta, cada nó em profundidade (id, tipo, nome, limites, rotação, preenchimento, traçado, d, efeitos, informações de mesclagem e booleanas, pilhas, modo de mesclagem e filtros) e a seleção. vector.getAppearance fornece as pilhas completas e filtros de um nó.
2. Planeje em camadas. Decida as formas, sua pilha (de baixo para cima) e seu agrupamento antes de desenhar. Comece a partir de primitivas (vector.addShape) e combine-as; escreva d bruto apenas para curvas que as primitivas não podem fazer.
3. Escreva em lotes. Coloque uma sequência de construção em um run_commands com atomic: true e um label, encadeando ids ("$0.id", "$last.ids"), de modo que seja uma etapa de desfazer que aplica tudo ou nada.
4. Prefira ao vivo, expanda por último. Use booleanos live: true, efeitos de caminho, envelopes, cantos e mesclagens ao vivo durante o design; asse com vector.expandAppearance, vector.expandBlend ou vector.outlineStroke apenas quando o usuário precisar de caminhos simples.
5. Verifique. vector.list novamente: limites onde você pretendia, sem nós soltos, nomes sensatos. vector.exportSvg fornece a marcação final; revise-a, ou renderize-a se puder, antes de entregá-la.

Melhores práticas

• Quadros para qualquer coisa que redimensione. Construa telas, cartões, botões e banners dentro de um quadro (vector.addFrame ou vector.frameSelection), defina as restrições de cada filho com vector.setResizing (fundos e divisores leftRight, ícones fixados em seu canto, títulos center), depois redimensione com vector.setFrame para produzir outros tamanhos a partir de um design. Exporte cada prancheta com vector.exportFrameSvg.
• Símbolos para repetições. Quando a mesma arte aparece várias vezes (ícones em um conjunto, árvores em uma cena, marcadores, uma marca de logotipo), crie-a uma vez e coloque instâncias (vector.makeSymbol, depois vector.placeSymbol com x / y ou um transform), de modo que uma edição em isolamento as altere a todas. Dê a cada um um nome claro. Use vector.setInstanceOptions fill / stroke para variantes de cor e hidden para descartar uma parte, em vez de desanexar; desanexe apenas quando uma cópia deve divergir permanentemente.
• Texto. Use texto de ponto para rótulos e títulos, texto de área (width, height) para qualquer coisa que deva ser ajustada, texto em um caminho para emblemas e selos. Verifique overflow no resumo que toda escrita de texto retorna: linhas ou caracteres ocultos significam que a caixa ou o caminho é muito pequeno. Mantenha uma ou duas famílias por design (vector.listFonts lista o que o shaper tem; uma família ausente desenha em um fallback e aparece em missingFonts). Estilize intervalos com vector.setTextStyle em vez de dividir o texto em nós separados, para que ainda edite como um parágrafo. Crie Contornos apenas para arte final ou logotipos que não devem depender de fontes; mantenha uma cópia como texto se puder mudar.
• Caminhos, traçados, pinceladas, booleanos, gradientes, pilhas, máscaras, sombras, conectores, restrições e texto vertical: leia references/best-practices.md primeiro.
• Não destrutivo primeiro. Booleanos ao vivo (vector.boolean com live: true), efeitos de caminho e envelopes mantêm os operandos editáveis. Um booleano destrutivo ou Pathfinder substitui suas entradas; faça isso por último, e apenas quando for solicitada saída plana.
• Agrupamento e nomenclatura. Agrupe as partes de um objeto (vector.group com um name), nomeie caminhos que importam (name em add), e mantenha a árvore rasa.
• Higiene SVG. Exporte com precision 2 ou 3 (padrão 3); maior apenas para pranchetas muito pequenas. Expanda efeitos, mesclagens e traçados de largura variável antes de entregar SVG a ferramentas que não leem os atributos data-vector-* do Pixerate; outros leitores veem a aparência desenhada, mas não a fonte ao vivo.

Comandos

Leitura

Comando	Use para
vector.list	Ler o documento: { width, height, nodes, selection, tool }. Cada nó tem id, tipo, nome, profundidade, bounds no espaço do documento, rotation (graus no sentido horário), visível, bloqueado, selecionado, e para caminhos fill, stroke, strokeWidth e d; grupos listam children, blend, liveBoolean, effects, mask. Os bounds de um grupo de máscara são seu resultado mascarado. Chame-o primeiro e após qualquer lote.
vector.shapeBuilderFaces	Listar as regiões em que os caminhos fornecidos dividem o plano: dados do caminho, área, um ponto dentro de cada uma e os ids dos caminhos que a preenchem. Use os pontos com vector.shapeBuilder.
vector.exportSvg	Obter o documento como marcação SVG independente ({ svg }); precision de 0 a 8 decimais (padrão 3).
vector.exportPdf	Obter um PDF vetorial pronto para impressão como uma URL de dados base64: uma página, ou uma por prancheta com pages: "artboards". Retorna { pdf, pages, bytes, notes }; verifique notes (filtros, máscaras de opacidade e texto sem fontes carregadas são omitidos).
vector.exportLottie	Obter o documento (ou ids) como JSON Lottie para players de animação: efeitos de caminho permanecem ao vivo como modificadores Lottie, gradientes como preenchimentos de gradiente. Retorna { lottie, notes }; leia notes para o que foi aproximado (filtros, gradientes de malha, texto sem contornos).

Criar e excluir

Comando	Use para
vector.traceImage	Transformar um PNG (URL de dados) em caminhos vetoriais em um grupo: modo threshold para arte de uma cor (logotipos, digitalizações, silhuetas; channel: "alpha" para recortes), modo color para um caminho empilhado por cor (colors 2–32). Aumente tolerance para menos âncoras, cornerRoundness 0 para polígonos nítidos. Coloque com x, y, width. Retorna { id, paths }; verifique contagens de subpaths e simplifique ou exclua manchas depois.
vector.mosaicImage	Estilizar um PNG como mosaico (cell px, shape quadrado / círculo, gap, colors): pixel art, murais em mosaico. Retorna { id, paths }, um caminho composto por cor.
vector.halftoneImage	Estilizar um PNG como pontos de meio-tom em uma tela girada (cell, angle, ink color ou nulo para as cores da imagem): looks de quadrinhos e pop art, efeitos de impressão.
vector.lowPolyImage	Estilizar um PNG como triângulos low-poly (cell, jitter, seed, colors): retratos e fundos geométricos.
vector.hatchImage	Estilizar um PNG como linhas de gravação que engrossam onde é escuro (cell espaçamento, angle, ink color): looks de nota, xilogravura e line-art.
vector.addPathByDimensions	Desenhar um caminho como um usuário de CAD digita: a partir de start, cada passo { length, angle } (graus anti-horários na página: 0 direita, 90 cima), { dx, dy } ou { x, y }; closed une as extremidades. Use para contornos técnicos exatos (suportes, plantas baixas, comprimentos e ângulos fornecidos) em vez de calcular coordenadas manualmente. Retorna { id, anchors }.
vector.addShape	Adicionar um kind rect, ellipse, polygon (sides, pelo menos 3), star (points, innerRatio 0 a 1) ou line em x, y, width, height (todos obrigatórios; para uma linha, largura e altura são o deslocamento da extremidade). cornerRadius e cornerKind dão cantos vivos; qualquer campo de estilo e name se aplicam. Usa o estilo padrão do editor para o que não for fornecido. Retorna { id }.
vector.addPath	Adicionar um caminho a partir de dados de caminho SVG d (M, L, H, V, C, S, Q, T, A, Z absolutos ou relativos; arcos e quadráticas tornam-se cúbicos) em unidades do documento, com name e campos de estilo; estilo não definido vem dos padrões do editor. Falha quando d não tem pontos. Retorna { id }.
vector.importSvg	Adicionar as formas da marcação SVG svg no topo do documento, ou substituir o documento com replace: true. Lê caminhos, formas básicas, grupos, transformações, gradientes lineares e radiais, referências clip-path / mask (como grupos de máscara) <text> (como texto de ponto: conteúdo, fonte, âncora e preenchimento) e <use> (como instâncias de símbolos feitos a partir do que referenciam); ignora imagens e filtros estrangeiros.
vector.importLottie	Adicionar um frame de uma animação Lottie (objeto ou texto) como grupos editáveis, ou substituir o documento (replace: true). Modificadores tornam-se efeitos ao vivo. Retorna { ids, notes }.
vector.delete	Excluir nós (ids).
vector.rename	Renomear nó id para name (seu nome no painel Camadas). Nomeie o que você cria pelo que é; renomeie as camadas do usuário apenas quando solicitado. Retorna { id, name }.

Estilo

Comando	Use para
vector.setStyle	Definir fill, stroke, strokeWidth, strokeLinecap (butt, round, square), strokeLinejoin (miter, round, bevel), strokeDasharray, fillRule (nonzero, evenodd), strokeAlign (center, inside, outside; apenas formas fechadas), startArrow / endArrow (triangle, arrow, open, circle, square, bar, ou null), arrowAlign (extend, tip), startArrowScale / endArrowScale (múltiplos da largura do traçado, padrão 1), strokeWidthProfile em ids. Grupos se aplicam a cada caminho dentro. Passe pelo menos um campo.
vector.setGradient	Editar o gradiente do preenchimento (target padrão) ou traçado de ids: type (linear, radial, conic, reflected, diamond), stops, angle (graus, 0 cima, sentido horário), cx / cy / r, start / end / width / focal explícitos, units, spread, interpolation (srgb padrão, linear, oklab), smoothness, strokeMode, aspect, reverse. Campos faltando mantêm seu valor; uma cor sólida torna-se um gradiente dela para branco. Retorna o

... (conteúdo truncado para tradução)