Pixerate/pixerate-brushes

Pinceles

Un pincel está compuesto por facetas que definen qué es y cómo se comporta, no qué motor lo dibuja. Solo son obligatorios id, name, kind y tip.shape; cualquier otro campo toma el valor predeterminado del motor que seleccionan las facetas, por lo que un pincel almacena solo lo que lo hace ser lo que es. La librería contiene los preajustes integrados (solo lectura) y los pinceles del usuario, compartidos por todos los editores que pintan.

Faceta (campo)	Qué contiene
Tipo	mark deposita un material; tool trabaja sobre pintura ya aplicada.
Medio y variedad	Marcas: qué deposita (paint, ink, dry, spray) y de qué tipo (oil, watercolor, gouache, pencil, charcoal, airbrush, marker, highlighter…). Descriptivo, para encontrar pinceles; un pincel húmedo cuya variedad es watercolor, gouache u oil pinta ese medio.
Herramienta	Herramientas: eraser, blender, smudge, y sobre pintura húmeda water, dryer, blow, blot, wet-blend, wet-drag.
Punta	shape (round, flat, chisel son elipses definidas por roundness y angle; bristle tiene un mechón; stamp toma la forma de stamps: un sello del editor editor:star, cualquier referencia a sticker de find_stickers, o una fuente de imagen source:<id> de list_brush_sources), tamaño en píxeles, dureza (una punta de imagen se desvanece hacia sus bordes por debajo de 1), espaciado, opacidad, flujo, modo de fusión, y grain: textura dentro de cada huella (source: un patrón como rough, canvas, sanded, o source:<id>; mode texturised permanece fijo en el lienzo, moving rueda con la punta; scale, depth, contrast, invert).
Marcas	continuous huellas (por defecto; en una punta de sello cada huella es la forma del primer sello, del color de pintura), scatter (un aerosol: gotitas repartidas por la punta, density, size), particles (hebras, muelles, cintas, chispas; puntos con textura de los sellos) u objects (cada marca es un sticker editable, con sus propios colores).
Dinámicas	Sensibilidad a la presión: presión a tamaño y opacidad, suavizado, inclinación, velocidad, interferencia (sizeJitter, angleJitter para rotación, opacityJitter, scatter), rotación, count (huellas por paso de espaciado, cada una con interferencia) y flip (espejo de huellas aleatorio: x, y, xy).
Comportamiento	surface dry, wet (ajustes de húmedo) o thick (ajustes de empaste); grain del papel; exchange (recogida y mezcla; un reservoir crea un Pincel Mezclador); strength de la herramienta.
Luz	Luz que emite el pincel (amount), más el spill y glow de capa sugeridos.
Movimiento	Animación después de pintar (pintura de efecto en vivo, waveSpeed de partículas).
Color	Un color default, una palette de hasta 16, own (siempre su propio color). Cada uno es un color hex o rgba(), un par claro/oscuro { light, dark }, un degradado o una pintura de efecto. Un degradado predeterminado siempre se pinta; un color sólido o claro/oscuro predeterminado se convierte en el color del editor al seleccionar el pincel (a menos que el usuario haya bloqueado el suyo), resuelto según el esquema de color. Los trazos de lienzo y los trazos de pincel vectoriales también lo toman, cuando no se les da un color. El lienzo y el vector tienen el mismo bloqueo (canvas.setColorLocked, vector.setColorLocked), y un color de lienzo tomado de un par claro/oscuro sigue el esquema como el del editor de pintura; los trazos vectoriales ya realizados conservan el suyo.

Cómo se asignan los medios a las facetas: un lápiz o carboncillo es dry con alto grain e inclinación; tinta es una punta redonda dura con presión a tamaño (un bolígrafo se afina con la velocidad); acuarela y óleo húmedo son paint en surface: 'wet'; empaste es surface: 'thick'; un aerógrafo es spray, suave y con poco flujo; un spray es spray con marks scatter; un bolígrafo, gel o rotulador de punta fina es ink con una punta pequeña y dura (un rotulador de punta fina sin presión a tamaño); cera y tiza son dry con alto grain; un rotulador fluorescente es ink / highlighter, una punta biselada multiplicativa con un poco de luz, spill radio 0, amarillo fluorescente por defecto; un pincel de sello es una punta stamp con marcas continuas; los pinceles de partículas y sticker son marks partículas u objetos en una punta stamp. Un pincel de imagen (una marca de carboncillo escaneada, una hoja, una textura de pincel seco) es una punta stamp cuyo sello es una fuente de imagen, generalmente con tip.grain, angleJitter, flip y un poco de scatter para que las repeticiones no se noten.

Fuentes de imagen son las imágenes de las que están hechas las puntas y el grano, almacenadas en la librería con sus bytes (una máscara gris, de máximo 512 píxeles) y su licencia. add_brush_source crea una a partir de un PNG: las marcas se leen de su transparencia, sus partes oscuras (un escaneo en papel) o sus partes claras (blanco sobre negro). Los archivos de librería (export_brushes) y las pinturas guardadas llevan las fuentes que sus pinceles nombran, para que pinten y se reproduzcan igual en cualquier lugar.

Perfiles de host

Cada host renderiza una parte de esto. check_brush indica qué rechaza un host (errores) y qué pinta sin (advertencias), cada uno con una solución; las listas y escrituras usan el host actual.

Host	Renderiza
Editor de pintura (paint)	Todo, incluyendo puntas de imagen y grano de punta.
Editor de imagen (image)	Huellas secas en puntas redondas, planas y biseladas, el Pincel Mezclador y la goma de borrar; sin superficie húmeda o empaste, partículas, objetos, puntas de sello o imagen, luz o movimiento; pinta sin grano de punta ni count. Seleccione uno con set_brush_preset.
Lienzo (canvas)	Pinceles de huella seca a lo largo de un trazado (sin herramientas, húmedo, empaste, partículas, objetos, puntas de sello o imagen, ni luz); se ignoran velocidad, grano de punta y count. Dibuje con uno como canvas.drawFreehand brush.
Trazos vectoriales (vector)	Como lienzo, más pintura húmeda (acuarela, gouache, óleos húmedos: simulados en su propia área del trazo, luego secados), el Pincel Mezclador y las herramientas de difuminado y mezcla (actuando sobre las formas debajo del trazo); los pinceles de luz pintan como color sólido. Las herramientas húmedas (agua, secador, soplar, mezclar húmedo, arrastrar húmedo, secante), pintura espesa, partículas, objetos y gomas de borrar son rechazadas. Dibuje con uno como vector.addBrushstroke brushId.

Cada host lista los preajustes que su perfil admite y los pinceles guardados de la librería que admite, y cada uno registra estas herramientas con su propio perfil, por lo que list_brush_presets muestra los pinceles de ese host. Las personas editan pinceles en cada host con el mismo editor de pinceles, con el mismo alcance: muestra solo los controles que usa el host (sin velocidad en lienzo, sin grano en el editor de imagen), y lo que el pincel tiene para otros hosts se conserva al guardar. Las herramientas siguen la misma regla (ver Errores comunes). Un pincel guardado usado en lienzo o trazos vectoriales se copia en el trazo, por lo que el documento se renderiza donde la librería no está; cambiar el pincel en la librería después no cambia los trazos ya dibujados.

Método de trabajo

1. Encontrar el pincel más cercano. list_brush_presets con medium, variety, kind o text. Lista solo lo que este host puede renderizar (all: true lista el resto con renderable).
2. Leerlo. describe_brush para la especificación completa, el motor al que se resuelve y su verificación.
3. Crear un pincel. create_brush con un id nuevo, un name, basedOn el preajuste más cercano y solo las facetas que cambian (los objetos se fusionan; las listas se reemplazan). Lea problems (valores ajustados o eliminados) y warnings. Un pincel que el host no puede renderizar es rechazado y no se guarda nada.
4. Mirarlo. preview_brush cuando el host tiene un renderizador; de lo contrario, pinte un trazo de prueba en el editor (set_brush con el nuevo id, luego paint_stroke).
5. Ajustarlo. update_brush con las facetas a cambiar, o unset para eliminar facetas enteras. Devuelve las rutas de hoja changed. Los preajustes integrados no se pueden cambiar: duplicate_brush primero.
6. Desde una imagen. add_brush_source con el PNG (channel cuando auto elige la parte incorrecta; conserve la licence con la que vino), luego create_brush con tip: { shape: "stamp", stamps: ["source:<id>"] } para una punta de imagen, o tip.grain.source para grano. list_brush_sources los lista y qué pinceles usan cada uno.
7. Importar un paquete. import_brush_pack con el archivo (base64), su fileName y la licence con la que vino. Lea brushes (con renderable para este host), unsupported (lo que no se asignó) y licence, luego preview_brush algunos y ajústelos con update_brush.
8. Compartirlo. export_brushes escribe un archivo de librería; import_brushes añade uno (los archivos versión 1 de pinceles antiguos del editor de pintura se migran). check_brush con host antes de pasar un pincel a otro editor.

Buenas prácticas

• Empiece desde el preajuste más cercano y cambie dos o tres facetas; un pincel desde cero obtiene valores predeterminados del motor que raramente se adaptan a un medio.
• Pruebe sobre el papel y el color en los que se usará el pincel: la respuesta del grano y los veladuras se ven diferentes en papel liso y rugoso.
• Dé a los pinceles de luz papel oscuro, y a los rotuladores fluorescentes un radio light.spill de 0 para que el resplandor se mantenga en el trazo.
• Mantenga variety veraz (es como la gente encuentra el pincel) y añada tags para la tarea (lettering, foliage).
• Dé a un pincel un colour.default solo cuando el medio tenga un color típico (bolígrafo azul, rotulador amarillo): al elegir el pincel se establece como color del usuario. Use un par claro/oscuro cuando el color correcto dependa del fondo (tiza blanca en una pizarra oscura, grafito en papel), y una palette para los otros colores habituales. Las tintas oscuras también necesitan un par (azul marino / azul claro, casi negro / casi blanco): un solo color oscuro predeterminado desaparece en un editor de esquema oscuro. Verifique cada lado contra el fondo para el que es (al menos 3:1). colour.own solo para pinceles que siempre deben pintar el suyo propio (un rotulador arcoíris).
• Las previsualizaciones y miniaturas eligen su propio color contra lo que se dibujan (el color predeterminado del pincel cuando se lee allí, si no, un color para el medio). No le dé a un pincel un color predeterminado solo para hacer visible su previsualización: elegir el pincel convierte ese predeterminado en el color del usuario.
• Las puntas de sello pintan la forma del sticker en el color de pintura; para mantener los colores propios de un sticker, use marks de objetos en su lugar.
• Puntas de imagen: recorte la imagen a la marca y dele un fondo transparente o liso, para que la huella sea la marca y no su caja. Espaciado 0.2–0.4 para una marca continua, por encima de 1 para huellas separadas; añada angleJitter, flip y scatter para que la misma imagen no se repita visiblemente.
• Grano: el grano texturised (por defecto) es una textura que el trazo revela, como el papel; el grano moving pertenece a la punta y rueda con ella (una esponja, un rodillo). Profundidad 0.4–0.7 se lee como textura; 1 deja solo los picos. Use tip.grain para la textura de la herramienta y behaviour.grain para la del papel.

Errores comunes

• Una faceta que el host rechaza. create_brush la rechaza, y update_brush rechaza un cambio que la añade, con la faceta y la solución; check_brush devuelve degraded, el pincel con esas facetas eliminadas, para empezar desde ahí.
• Ajustar un pincel en un host que no puede pintarlo todo. update_brush mantiene lo que el pincel ya tiene para otros hosts (la luz de un pincel de pintura, cambiada desde lienzo) y lo lista en kept; no se elimina. Para hacer una copia solo para este host, use create_brush desde el pincel degraded de check_brush.
• Ids. Los ids integrados no se pueden reutilizar ni cambiar; un id ya ocupado es rechazado (en su lugar, actualícelo).
• Sellos. Cualquier marca toma cualquier referencia a sticker de find_stickers, o un sello del editor (editor:star…). Una referencia que la librería de stickers del host no puede cargar es rechazada con las referencias más cercanas. Solo el editor de pintura renderiza puntas de sello y marcas scatter; lienzo, vector y el editor de imagen las rechazan (check_brush lo indica).
• Fuentes de imagen. Se rechaza un source:<id> que la librería no tiene, con los ids más cercanos; añádalo primero. Reemplazar la imagen de una fuente (overwrite) cambia todos los pinceles que la nombran, pero no los trazos ya pintados. Las marcas de objetos solo toman stickers, por lo que una fuente de imagen allí se elimina (problems lo indica). Los paquetes de pinceles suelen tener licencia solo para uso personal: conserve el texto de licence con la fuente.
• Paquetes de pinceles. Solo se importan las puntas (y el grano de Procreate): las dinámicas, curvas de lápiz, patrones, pinceles duales y ajustes de húmedo se listan en unsupported, por lo que los pinceles importados pintan con una sensación predeterminada; ajústelos. Las puntas de imagen importadas son puntas de sello, por lo que lienzo, vector y el editor de imagen no pueden pintarlas (renderable false). Los paquetes suelen ser solo para uso personal: pase y conserve su licence; nunca redistribuya un archivo de librería de pinceles importados sin verificarlo.
• Valores fuera de rango son rechazados por el esquema (tip.size es 1..2500 px); un pincel almacenado se ajusta al importar y se notifica en problems.
• El editor de pintura pinta desde esta librería. Su set_brush selecciona un pincel por id aquí y coloca facetas sobre él sin guardar; create_brush / update_brush almacenan uno. Un host de pintura registra estas herramientas con su propia previsualización (createPaintBrushLibraryToolProvider), por lo que el editor de pintura no tiene lista, guardar, exportar, importar ni herramientas de miniatura propias.

Skills de flujo de trabajo

• pixerate-brushes-design: desde una descripción ("un rotulador fluorescente rosa suave", "tiza para el lienzo") hasta un pincel guardado y verificado.

Referencia de herramientas

Herramienta	Uso
list_brush_presets	Encontrar pinceles que este host renderiza: kind, medium, variety, tool, tag, text, source (all, builtin, user), all, offset, limit. Devuelve brushes (id, name, builtin, kind, medium, variety o tool, category, engine, tip, size, marks, surface, light) y total. Llame primero.
describe_brush	Un pincel por id: su faceta completa brush (con su colour: default, palette, own), builtin, engine, category y check para este host (stamps y stickers incluidos). Los ids desconocidos son rechazados con los más cercanos.
create_brush	Guardar un pincel nuevo: id, name, opcional basedOn, y las facetas, colour incluido (para mantener el pincel actual de un editor, pase el brush que devuelve su get_brush). Normalizado y verificado para este host (y su librería de stickers, para puntas de sello); los pinceles rechazados no guardan nada. Devuelve id, brush, engine, problems, warnings.
update_brush	Actualiza las facetas de un pincel existente por id: envía las facetas a fusionar (reemplazan las existentes; los objetos se fusionan; las listas se reemplazan) y unset como un array de rutas de faceta para eliminar. Los preajustes integrados son rechazados (duplique primero). Devuelve id, brush, engine, changed (rutas cambiadas), kept (rutas sin cambios de otros hosts), problems, warnings.
duplicate_brush	Copia un pincel a un nuevo id (o genera uno); basedOn se ignora. Devuelve el nuevo id.
remove_brush	Elimina un pincel por id; los preajustes integrados son rechazados. Devuelve el id eliminado.
check_brush	Por host y brush: devuelve errors (error, facet, closest en stamps o sources) y warnings (warning, facet). Si es posible representarlo de forma degradada, devuelve también el brush degraded con esas facetas eliminadas.
preview_brush	Devuelve un svg de vista previa del pincel (o un data: png dimensionado), dado brush y width (máx. 512). Cuando el host tiene un renderizador; de lo contrario, available es falso. Los pinceles sin testura o con textura texturised se muestran con papel.
add_brush_source	Crea una fuente de imagen desde un image PNG, con name único o generado, licence (obligatoria), y channel (transparency, dark, light, auto). Devuelve id (source: con el id numérico). Una fuente con el mismo hash que una existente es rechazada (se devuelve su id).
list_brush_sources	Lista las fuentes de imagen: cada una con id, name, licence, size y usedBy (array de ids de pinceles).
export_brushes	Toma un array de ids de pinceles a exportar. Devuelve library (base64 de un archivo binario).
import_brushes	Importa un archivo library (base64) y lo combina: brushes (cada uno con renderable), sources. Los pinceles con ids que ya existen no se importan (advierte).
import_brush_pack	Importa un archivo de paquete de pinceles (Photoshop .abr o Procreate .brush / .brushset) como base64 con fileName y licence. Devuelve brushes (cada uno: id, name, kind, medium/variety/tool, engine, renderable; los pinceles no soportados tienen solo name y licencia) y unsupported (lo que no se asignó) - ver Errores comunes. Siempre devuelve la licence; pásela a add_brush_source.