Pixerate/pixerate-brushes

Pinceaux

Un pinceau est composé de facettes qui décrivent ce qu'il est et comment il se comporte, et non quel moteur le dessine. Seuls id, name, kind et tip.shape sont obligatoires ; tous les autres champs prennent la valeur par défaut du moteur que les facettes sélectionnent, donc un pinceau ne stocke que ce qui le rend unique. La bibliothèque contient les préréglages intégrés (lecture seule) et les pinceaux de l'utilisateur, partagés par tous les éditeurs qui peignent.

Facette (champ)	Ce qu'elle contient
Type (Kind)	mark dépose une matière ; tool agit sur la peinture déjà appliquée.
Médium et variété	Marques : ce qu'elles déposent (paint, ink, dry, spray) et de quel type (oil, watercolor, gouache, pencil, charcoal, airbrush, marker, highlighter…). Descriptif, pour trouver les pinceaux ; un pinceau humide dont la variété est watercolor, gouache ou oil peint ce médium.
Outil (Tool)	Outils : eraser, blender, smudge, et sur peinture humide water, dryer, blow, blot, wet-blend, wet-drag.
Pointe (Tip)	shape (round, flat, chisel sont des ellipses définies par roundness et angle ; bristle a une touffe ; stamp prend la forme de stamps : un tampon d'éditeur editor:star, toute référence d'autocollant de find_stickers, ou une source d'image source:<id> de list_brush_sources), taille en px, dureté (une pointe d'image s'estompe vers ses bords en dessous de 1), espacement, opacité, flux, mode de fusion, et grain : texture à l'intérieur de chaque dépôt (source : un motif tel que rough, canvas, sanded, ou source:<id> ; mode texturised reste fixe sur le canevas, moving roule avec la pointe ; scale, depth, contrast, invert).
Marques (Marks)	continuous dépôts (par défaut ; sur une pointe tampon, chaque dépôt a la forme du premier tampon, dans la couleur de peinture), scatter (une pulvérisation : gouttelettes sur la pointe, density, size), particles (brins, ressorts, rubans, étincelles ; points texturés à partir des tampons) ou objects (chaque marque est un autocollant modifiable, dans ses propres couleurs).
Dynamique (Dynamics)	Sensibilité à la pression : pression sur la taille et l'opacité, lissage, inclinaison, vélocité, gigue (sizeJitter, angleJitter pour la rotation, opacityJitter, scatter), rotation, count (dépôts par pas d'espacement, chacun avec une gigue) et flip (dépôts miroir aléatoires : x, y, xy).
Comportement (Behaviour)	surface dry, wet (réglages wet) ou thick (réglages d'empâtement thick) ; grain du papier ; exchange (prélèvement et mélange ; un reservoir crée un Mixer Brush) ; force de l'outil strength.
Lumière (Light)	Lumière émise par le pinceau (amount), plus les effets de couche suggérés spill et glow.
Mouvement (Motion)	Animation après la peinture (effet de peinture en direct, waveSpeed des particules).
Couleur (Colour)	Une couleur default, une palette de 16 couleurs maximum, own (toujours sa propre couleur). Chacune est une couleur hexadécimale ou rgba(), une paire clair/foncé { light, dark }, un dégradé ou une peinture à effet. Un dégradé par défaut est toujours peint ; un défaut solide ou clair/foncé devient la couleur de l'éditeur lorsque le pinceau est choisi (sauf si l'utilisateur a verrouillé la sienne), résolue selon le jeu de couleurs. Les traits du canevas et les traits vectoriels l'utilisent également lorsqu'aucune couleur ne leur est donnée. Le canevas et le vecteur ont le même verrouillage (canvas.setColorLocked, vector.setColorLocked), et une couleur de canevas prise à partir d'un défaut clair/foncé suit le jeu de couleurs comme l'éditeur de peinture ; les traits vectoriels déjà réalisés conservent les leurs.

Correspondance entre les médias et les facettes : un crayon ou un fusain est dry avec un grain élevé et une inclinaison ; l'encre est une pointe ronde dure avec une pression sur la taille (un stylo s'affine avec la vélocité) ; l'aquarelle et l'huile humide sont paint sur surface: 'wet' ; l'empâtement est surface: 'thick' ; un aérographe est spray, doux et à faible flux ; une bombe aérosol est spray avec des marques scatter ; un stylo à bille, un stylo gel ou un feutre fin est ink avec une petite pointe dure (un feutre fin sans pression sur la taille) ; le crayon gras et la craie sont dry avec un grain élevé ; un surligneur est ink / highlighter, une pointe biseautée multiplicative avec un peu de lumière, spill radius 0, jaune fluorescent par défaut ; un pinceau tampon est une pointe stamp avec des marques continues ; les pinceaux particules et autocollants sont des marques particles ou objects sur une pointe stamp. Un pinceau d'image (une marque de fusain scannée, une feuille, une texture de pinceau sec) est une pointe stamp dont le tampon est une source d'image, généralement avec tip.grain, angleJitter, flip et un peu de scatter pour que les répétitions ne soient pas visibles.

Les sources d'image sont les images à partir desquelles les pointes et le grain sont fabriqués, conservées dans la bibliothèque avec leurs octets (un masque gris, 512 px maximum) et leur licence. add_brush_source en crée une à partir d'un PNG : les marques sont lues à partir de sa transparence, de ses parties sombres (un scan sur papier) ou de ses parties claires (blanc sur noir). Les fichiers de bibliothèque (export_brushes) et les peintures enregistrées contiennent les sources que leurs pinceaux nomment, afin qu'ils peignent et rejouent partout de la même manière.

Profils hôtes

Chaque hôte restitue une partie de cela. check_brush indique ce qu'un hôte refuse (erreurs) et ce qu'il peint sans (avertissements), chacun avec une solution ; les listes et les écritures utilisent l'hôte actuel.

Hôte	Restitue
Éditeur de peinture (paint)	Tout, pointes d'image et grain de pointe inclus.
Éditeur d'image (image)	Dépôts secs sur pointes rondes, plates et biseautées, le Mixer Brush et la gomme ; pas de surface humide ou épaisse, de particules, d'objets, de pointes tampon ou d'image, de lumière ou de mouvement ; il peint sans grain de pointe ni count. Choisissez-en un avec set_brush_preset.
Canevas (canvas)	Pinceaux à dépôts secs le long d'un chemin (pas d'outils, humide, épais, particules, objets, pointes tampon ou d'image, ou lumière) ; la vélocité, le grain de pointe et count sont ignorés. Dessinez avec un comme canvas.drawFreehand brush.
Traits vectoriels (vector)	Comme le canevas, plus la peinture humide (aquarelle, gouache, huiles humides : simulée dans la propre zone du trait, puis séchée), le Mixer Brush, et les outils de maculage et de mélange (agissant sur les formes sous le trait) ; les pinceaux lumineux peignent en couleur unie. Les outils humides (eau, sèche-cheveux, souffle, mélange humide, traînée humide, buvard), la peinture épaisse, les particules, les objets et les gommes sont refusés. Dessinez avec un comme vector.addBrushstroke brushId.

Chaque hôte liste les préréglages que son profil admet et les pinceaux enregistrés de la bibliothèque qu'il admet, et chacun enregistre ces outils avec son propre profil, donc list_brush_presets montre les pinceaux de cet hôte. Les gens modifient les pinceaux dans chaque hôte avec le même éditeur de pinceaux, limité de la même manière : il montre uniquement les contrôles que l'hôte utilise (pas de vélocité sur le canevas, pas de grain dans l'éditeur d'image), et ce que le pinceau a pour les autres hôtes est conservé lors de l'enregistrement. Les outils suivent la même règle (voir Pièges). Un pinceau enregistré utilisé dans des traits de canevas ou vectoriels est copié dans le trait, de sorte que le document rend là où la bibliothèque n'est pas ; modifier le pinceau dans la bibliothèque plus tard ne modifie pas les traits déjà dessinés.

Méthode de travail

1. Trouvez le pinceau le plus proche. list_brush_presets avec medium, variety, kind ou text. Il liste uniquement ce que cet hôte peut restituer (all: true liste le reste avec renderable).
2. Lisez-le. describe_brush pour la spécification complète, le moteur vers lequel il résout et sa vérification.
3. Créez un pinceau. create_brush avec un nouvel id, un name, basedOn le préréglage le plus proche et uniquement les facettes qui changent (les objets fusionnent ; les listes remplacent). Lisez problems (valeurs limitées ou supprimées) et warnings. Un pinceau que l'hôte ne peut pas restituer est refusé et rien n'est enregistré.
4. Regardez-le. preview_brush lorsque l'hôte a un moteur de rendu ; sinon, peignez un trait de test dans l'éditeur (set_brush avec le nouvel id, puis paint_stroke).
5. Réglez-le. update_brush avec les facettes à modifier, ou unset pour supprimer des facettes entières. Cela renvoie les chemins de feuille changed. Les préréglages intégrés ne peuvent pas être modifiés : duplicate_brush d'abord.
6. À partir d'une image. add_brush_source avec le PNG (channel lorsque auto choisit la mauvaise partie ; conservez la licence avec laquelle il est venu), puis create_brush avec tip: { shape: "stamp", stamps: ["source:<id>"] } pour une pointe d'image, ou tip.grain.source pour le grain. list_brush_sources les liste et quels pinceaux utilisent chacun.
7. Importez un pack. import_brush_pack avec le fichier (base64), son fileName et la licence avec laquelle il est venu. Lisez brushes (avec renderable pour cet hôte), unsupported (ce qui n'a pas été mappé) et licence, puis preview_brush quelques-uns et réglez-les avec update_brush.
8. Partagez-le. export_brushes écrit un fichier de bibliothèque ; import_brushes en ajoute un (les fichiers version 1 des anciens pinceaux de l'éditeur de peinture sont migrés). check_brush avec host avant de remettre un pinceau à un autre éditeur.

Bonnes pratiques

• Partez du préréglage le plus proche et modifiez deux ou trois facettes ; un pinceau créé de toutes pièces obtient les valeurs par défaut du moteur qui conviennent rarement à un médium.
• Testez sur le papier et la couleur sur lesquels le pinceau sera utilisé : la réponse du grain et les glacis sont différents sur du papier lisse et rugueux.
• Donnez du papier foncé aux pinceaux lumineux et donnez aux surligneurs un light.spill radius de 0 pour que la lueur reste sur le trait.
• Gardez variety véridique (c'est ainsi que les gens trouvent le pinceau) et ajoutez tags pour le travail (lettering, foliage).
• Donnez à un pinceau un colour.default uniquement lorsque le médium a une couleur typique (stylo à bille bleu, surligneur jaune) : choisir le pinceau le définit comme la couleur de l'utilisateur. Utilisez une paire clair/foncé lorsque la bonne couleur dépend de l'arrière-plan (craie blanche sur un tableau noir, graphite sur papier), et une palette pour les autres couleurs habituelles. Les encres foncées ont besoin d'une paire aussi (bleu marine / bleu clair, presque noir / presque blanc) : un seul défaut foncé disparaît dans un éditeur à jeu de couleurs sombre. Vérifiez chaque côté par rapport à l'arrière-plan auquel il est destiné (au moins 3:1). colour.own uniquement pour les pinceaux qui doivent toujours peindre leur propre couleur (un marqueur arc-en-ciel).
• Les aperçus et les vignettes choisissent leur propre couleur par rapport à ce sur quoi ils sont dessinés (la valeur par défaut du pinceau lorsqu'il la lit, sinon une couleur pour le médium). Ne donnez pas de valeur par défaut à un pinceau juste pour rendre son aperçu visible : choisir le pinceau fait de cette valeur par défaut la couleur de l'utilisateur.
• Les pointes tampons peignent la forme de l'autocollant dans la couleur de peinture ; pour conserver les propres couleurs d'un autocollant, utilisez des objets marks à la place.
• Pointes d'image : recadrez l'image sur la marque et donnez-lui un arrière-plan transparent ou uni, de sorte que le dépôt soit la marque et non son cadre. Espacement 0,2–0,4 pour une marque continue, supérieur à 1 pour des impressions séparées ; ajoutez angleJitter, flip et scatter pour que la même image ne se répète pas visiblement.
• Grain : le grain texturised (par défaut) est une texture que le trait révèle, comme le papier ; le grain moving appartient à la pointe et roule avec elle (une éponge, un rouleau). Une profondeur de 0,4 à 0,7 se lit comme une texture ; 1 ne laisse que les pics. Utilisez tip.grain pour la texture de l'outil et behaviour.grain pour celle du papier.

Pièges

• Une facette que l'hôte refuse. create_brush la refuse, et update_brush refuse une modification qui l'ajoute, avec la facette et la solution ; check_brush renvoie degraded, le pinceau avec ces facettes supprimées, pour partir de là.
• Régler un pinceau dans un hôte qui ne peut pas tout peindre. update_brush conserve ce que le pinceau a déjà pour les autres hôtes (la lumière d'un pinceau de peinture, modifiée à partir du canevas) et le liste dans kept ; il n'est pas supprimé. Pour faire une copie pour cet hôte uniquement, create_brush à partir du pinceau degraded de check_brush à la place.
• Ids. Les ids intégrés ne peuvent pas être réutilisés ou modifiés ; un id déjà pris est refusé (mettez-le à jour à la place).
• Tampons. Toutes les marques acceptent toute référence d'autocollant de find_stickers, ou un tampon d'éditeur (editor:star…). Une référence que la bibliothèque d'autocollants de l'hôte ne peut pas charger est refusée avec les références les plus proches. Seul l'éditeur de peinture restitue les pointes tampon et les marques dispersées ; le canevas, le vecteur et l'éditeur d'image les refusent (check_brush le dit).
• Sources d'image. Une source:<id> que la bibliothèque ne possède pas est refusée, avec les ids les plus proches ; ajoutez-la d'abord. Remplacer l'image d'une source (overwrite) modifie tous les pinceaux qui la nomment, mais pas les traits déjà peints. Les marques d'objets n'acceptent que les autocollants, donc une source d'image y est supprimée (problems le dit). Les packs de pinceaux sont souvent sous licence pour usage personnel uniquement : conservez le texte de la licence avec la source.
• Packs de pinceaux. Seules les pointes (et le grain Procreate) sont importées : la dynamique, les courbes de crayon, les motifs, les pinceaux doubles et les réglages humides sont listés dans unsupported, donc les pinceaux importés peignent avec une sensation par défaut ; réglez-les. Les pointes d'image importées sont des pointes tampon, donc le canevas, le vecteur et l'éditeur d'image ne peuvent pas les peindre (renderable false). Les packs sont souvent pour usage personnel uniquement : transmettez et conservez leur licence ; ne redistribuez jamais un fichier de bibliothèque de pinceaux importés sans le vérifier.
• Les valeurs hors limites sont refusées par le schéma (tip.size est 1..2500 px) ; un pinceau stocké est limité lors de l'importation et signalé dans problems.
• L'éditeur de peinture peint à partir de cette bibliothèque. Son set_brush sélectionne un pinceau par id ici et applique les facettes par-dessus sans enregistrer ; create_brush / update_brush en stockent un. Un hôte de peinture enregistre ces outils avec son propre aperçu (createPaintBrushLibraryToolProvider), donc l'éditeur de peinture n'a pas de liste, d'enregistrement, d'exportation, d'importation ou d'outils de vignette qui lui sont propres.

Compétences de flux de travail

• pixerate-brushes-design : à partir d'une description ("un surligneur rose doux", "craie pour le canevas") jusqu'à un pinceau enregistré et vérifié.

Référence des outils

Outil	Utilisation
list_brush_presets	Trouver les pinceaux que cet hôte restitue : kind, medium, variety, tool, tag, text, source (all, builtin, user), all, offset, limit. Renvoie brushes (id, name, builtin, kind, medium, variety ou tool, category, engine, tip, size, marks, surface, light) et total. Appelez d'abord.
describe_brush	Un pinceau par id : sa facette complète brush (avec son colour : default, palette, own), builtin, engine, category et check pour cet hôte (autocollants de tampon inclus). Les ids inconnus sont refusés avec les plus proches.
create_brush	Enregistrer un nouveau pinceau : id, name, basedOn optionnel, et les facettes, colour inclus (pour conserver le pinceau actuel d'un éditeur, passez le brush que son get_brush renvoie). Normalisé et vérifié pour cet hôte (et sa bibliothèque d'autocollants, pour les pointes tampon) ; les pinceaux refusés n'enregistrent rien. Renvoie id, brush, engine, problems, warnings.
update_brush	Modifier un pinceau sauvegardé (ou un doublon) : id, name, les facettes à appliquer (les objets fusionnent ; les listes remplacent), unset pour supprimer des facettes entières (['colour', 'tip.grain']). Renvoie brush, engine, changed (chemins de feuille des valeurs qui ont changé), kept (valeurs conservées pour d'autres hôtes), warnings, problems. Les préréglages intégrés sont refusés.
duplicate_brush	Copier un pinceau : id et basedOn optionnel pour partir d'un autre. Le doublon est enregistré comme pinceau utilisateur (builtin: false). Renvoie id et brush.
remove_brush	Supprimer un pinceau utilisateur par id. Les préréglages intégrés et les pinceaux en cours d'utilisation sont refusés. Renvoie un booléen removed.
preview_brush	Aperçu dans l'interface utilisateur du pinceau par id (ou une courte spécification en tant que brush), format (png, jpeg), renvoie l'image en base64. Aucun aperçu n'est disponible pour les hôtes canevas et vecteur ; les marques d'objets ne sont pas rendues.
check_brush	Erreurs et avertissements pour le host actuel (ou un host donné), brush à vérifier. Renvoie une liste de hosts, chaque hôte avec des errors (les facettes qui ne restituent rien) et des warnings (ignorées), chacune avec un fix et un brush degraded (nécessaire lorsque l'hôte ne restituera aucun trait). Les préréglages intégrés sont vérifiés à partir du magasin.
export_brushes	Écrire un fichier de bibliothèque : brushes (liste d'ids de pinceaux, ou 'all', 'user', 'builtin'), format (un ou plusieurs de 'library', 'abr', 'brushset'), includeSources (booléen, par défaut true). Renvoie files : un tableau d'objets { fileName, base64 }. Le fichier 'library' comprend les pinceaux et leurs sources d'image ; les fichiers .abr et .brushset ne peuvent contenir que ce qu'ils mappent.
import_brushes	Ajouter un fichier de bibliothèque à partir de file (base64) et fileName. Les sources d'image sont extraites ou nouvellement créées. Renvoie brushes (ids et renderable pour cet hôte) et total. La version 1 (pinceaux anciens de l'éditeur de peinture) est migrée.
import_brush_pack	Importer un pack de pinceaux à partir de file (base64), fileName, licence. Les pointes (et le grain Procreate) sont importées ; les packs peuvent avoir des unsupported (dynamiques, motifs, pinceaux doubles, courbes). Renvoie brushes (ids et renderable pour cet hôte), total, unsupported (liste de ce qui n'a pas été mappé dans chaque pinceau) et licence (texte).
add_brush_source	Ajouter une source d'image à la bibliothèque : image PNG (base64), channel ('auto', 'transparency', 'dark', 'light'), et licence. Renvoie id (source:), size (px, le côté le plus long limité à 512).
list_brush_sources	Lister les sources d'image disponibles : all (booléen, défaut false : seulement celles non utilisées). Renvoie sources : un tableau de { id, thumbnail, width, height, channel, usedBy: [brushId] }.
get_brush	Souvent utilisé en interne par les hôtes. Le get_brush de l'éditeur de peinture renvoie le pinceau appliqué (bibliothèque de peinture, avec set_brush sur elle). Utilisez describe_brush à la place.