Pixerate/pixerate-brushes

画笔

画笔由刻面组成，这些刻面描述其属性与行为，而非由哪个引擎绘制。仅 id、name、kind 和 tip.shape 是必需的；其余字段采用刻面所选引擎的默认值，因此画笔仅存储使其独特的部分。库中保存了内置预设（只读）和用户的画笔，供所有支持绘画的编辑器共享。

刻面（字段）	内容
种类	mark 用于投放材料；tool 用于处理已存在的颜料。
介质与变体	笔触：投放的内容（paint、ink、dry、spray）和类型（oil、watercolor、gouache、pencil、charcoal、airbrush、marker、highlighter…）。描述性，用于查找画笔；变体为 watercolor、gouache 或 oil 的湿画笔会绘制该介质。
工具	工具：eraser、blender、smudge，以及在湿颜料上使用的 water、dryer、blow、blot、wet-blend、wet-drag。
笔尖	shape（round、flat、chisel 是由 roundness 和 angle 设定的椭圆；bristle 有簇毛；stamp 采用 stamps 的形状：编辑器印章 editor:star、来自 find_stickers 的任何贴纸引用，或来自 list_brush_sources 的图像源 source:<id>），以像素为单位的尺寸、硬度（图像笔尖在低于1时向边缘淡出）、间距、不透明度、流量、混合模式，以及 grain：每个墨点内的纹理（source：图案如 rough、canvas、sanded，或 source:<id>；mode 为 texturised 时纹理固定在画布上，moving 时随笔尖滚动；scale、depth、contrast、invert）。
墨点	continuous 墨点（默认；印章笔尖的每个墨点都是第一个印章的形状，使用颜料颜色）、scatter（喷雾：笔尖上的液滴，含 density、size）、particles（线条、弹簧、丝带、火花；来自印章的纹理点）或 objects（每个笔触为可编辑的贴纸，使用自身颜色）。
动态	笔压：压力影响尺寸与不透明度、平滑度、倾斜、速度、抖动（sizeJitter、angleJitter 用于旋转、opacityJitter、scatter）、旋转、count（每个间距步长的墨点数，每个都抖动）和 flip（随机镜像墨点：x、y、xy）。
行为	surface 为 dry、wet（湿设置）或 thick（厚涂设置）；纸张 grain；exchange（拾取与混合；reservoir 创建混合画笔）；工具 strength。
光照	画笔发出的光（amount），以及建议的图层 spill 和 glow。
运动	绘画后的动画（实时效果绘画、粒子 waveSpeed）。
颜色	一个 default 颜色、一个最多16色的 palette、own（始终使用自身颜色）。每个颜色可以是十六进制或 rgba() 颜色、亮/暗对 { light, dark }、渐变或效果绘画。渐变默认始终被绘制；纯色或亮/暗默认在选择画笔时成为编辑器的颜色（除非用户锁定），并根据配色方案解析。画布描边和矢量画笔描边在没有指定颜色时也使用它。画布和矢量具有相同的锁定（canvas.setColorLocked、vector.setColorLocked），从亮/暗默认获取的画布颜色会像绘画编辑器一样跟随配色方案；已绘制的矢量描边保持其颜色。

介质如何映射到刻面：铅笔或炭笔为 dry，具有高 grain 和倾斜；墨水为硬圆笔尖，压力影响尺寸（钢笔随速度变细）；水彩和湿油画为表面为 'wet' 的 paint；厚涂为 surface: 'thick'；喷枪为 spray，柔和且低流量；喷罐为带有 marks 分散的 spray；圆珠笔、凝胶笔或极细笔为带有小硬笔尖的 ink（极细笔无压力影响尺寸）；蜡笔和粉笔为具有高 grain 的 dry；荧光笔为 ink / highlighter，一个乘法的凿形笔尖，带有一点光照，spill 半径为0，默认荧光黄色；印章画笔为带有连续墨点的 stamp 笔尖；粒子和贴纸画笔为 marks 粒子或对象，位于 stamp 笔尖上。图像画笔（扫描的木炭笔触、树叶、干笔刷纹理）是一个印章笔尖，其印章是图像源，通常带有 tip.grain、angleJitter、flip 和少量 scatter，以防止重复明显。

图像源是笔尖和纹理所使用的图像，存储在库中，包含其字节（灰度蒙版，最大512像素）和许可信息。add_brush_source 从PNG创建图像源：从透明度、暗部（纸上的扫描）或亮部（白底黑图）读取笔触。库文件（export_brushes）和保存的画作会携带其画笔使用的图像源名称，以便在任何地方绘制和回放。

宿主配置文件

每个宿主渲染其中的一部分。check_brush 指示宿主拒绝的内容（错误）和无法绘制的内容（警告），每个都附带修复方法；列表和写入使用当前宿主。

宿主	渲染内容
绘画编辑器（paint）	所有内容，包括图像笔尖和笔尖纹理。
图像编辑器（image）	圆形、扁平与凿形笔尖上的干墨点、混合画笔和橡皮擦；无湿或厚表面、粒子、对象、印章或图像笔尖、光照或运动；绘制时不带笔尖纹理和 count。使用 set_brush_preset 选择。
画布（canvas）	沿路径的干墨点画笔（无工具、湿、厚、粒子、对象、印章或图像笔尖、或光照）；忽略速度、笔尖纹理和 count。使用 canvas.drawFreehand brush 绘制。
矢量描边（vector）	与画布相同，加上湿颜料（水彩、水粉、湿油画：在描边自身区域内模拟，然后干燥）、混合画笔，以及污迹和混合工具（作用于描边下方的形状）；光照画笔作为纯色绘制。湿工具（水、吹风机、吹风、湿混、湿拖、吸墨）、厚涂、粒子、对象和橡皮擦被拒绝。使用 vector.addBrushstroke brushId 绘制。

每个宿主列出其配置文件允许的预设和库中保存的画笔，并注册这些工具到其自身的配置文件，因此 list_brush_presets 显示该宿主的画笔。用户在每个宿主中使用相同的画笔编辑器编辑画笔，范围相同：仅显示宿主使用的控件（画布上无速度，图像编辑器中无纹理），并且画笔为其他宿主保存的内容保持不变。工具遵循相同规则（参见陷阱）。在画布或矢量描边中使用的已保存画笔会被复制到描边中，因此文档在没有库的位置也能渲染；之后修改库中的画笔不会改变已绘制的描边。

工作方法

1. 查找最近的画笔。 使用 medium、variety、kind 或 text 调用 list_brush_presets。它仅列出此宿主可渲染的内容（all: true 列出其余内容，并带有 renderable 标记）。
2. 读取它。 使用 describe_brush 获取完整规格、解析到的引擎及其检查结果。
3. 制作画笔。 使用新的 id、name、basedOn 最近的预设以及仅更改的刻面（对象合并；列表替换）调用 create_brush。读取 problems（值被钳制或舍弃）和 warnings。宿主无法渲染的画笔会被拒绝且不保存任何内容。
4. 查看它。 当宿主有渲染器时使用 preview_brush；否则在编辑器中绘制测试描边（使用新ID设置画笔，然后 paint_stroke）。
5. 调整它。 使用要更改的刻面调用 update_brush，或使用 unset 删除整个刻面。它返回已更改的叶路径 changed。内置预设无法更改：先 duplicate_brush。
6. 从图像制作。 使用PNG调用 add_brush_source（channel 在 auto 选错时使用；保留随附的 licence），然后使用 tip: { shape: "stamp", stamps: ["source:<id>"] } 创建图像笔尖，或使用 tip.grain.source 创建纹理。list_brush_sources 列出它们以及每个被哪些画笔使用。
7. 导入包。 使用文件（base64）、其 fileName 和随附的 licence 调用 import_brush_pack。读取 brushes（带此宿主的 renderable）、unsupported（未映射的内容）和 licence，然后预览几个并使用 update_brush 调整它们。
8. 共享它。 export_brushes 写入库文件；import_brushes 添加一个（版本1的绘画编辑器旧画笔文件会被迁移）。在交给另一个编辑器之前，使用 host 参数调用 check_brush。

最佳实践

• 从最近的预设开始，更改两三个刻面；从头创建的画笔会获得很少适合介质的引擎默认值。
• 在画笔将要使用的纸张和颜色上测试：纹理响应和釉面效果在光滑和粗糙纸张上不同。
• 给光照画笔深色纸张，给荧光笔 light.spill 半径为0，使发光保持在描边内。
• 保持 variety 真实（这是人们查找画笔的方式），并为特定用途添加 tags（例如 lettering、foliage）。
• 仅在介质有典型颜色时（蓝色圆珠笔、黄色荧光笔）为画笔设置 colour.default：选择画笔会将其设置为用户颜色。当正确颜色取决于背景时（白粉笔在黑板上，石墨在纸上），使用亮/暗对，并为其他常用颜色设置 palette。深色墨水也需要一对（海军蓝/浅蓝、近黑/近白）：单一深色默认值在深色方案的编辑器中会消失。对照背景检查每一侧（至少3:1）。仅对必须始终绘制自身颜色的画笔使用 colour.own（例如彩虹马克笔）。
• 预览和缩略图会根据绘制背景选择自己的颜色（如果有则使用画笔默认颜色，否则使用适合介质的颜色）。不要仅仅为了让预览可见而给画笔设置默认值：选择画笔会使该默认值成为用户颜色。
• 印章笔尖以颜料颜色绘制贴纸形状；要保留贴纸自身颜色，请使用 marks 对象。
• 图像笔尖：将图像裁剪为笔触并设置透明或纯色背景，使墨点就是笔触而不是其方框。间距0.2–0.4用于连续笔触，大于1用于单独印记；添加 angleJitter、flip 和 scatter 使相同图像不会明显重复。
• 纹理：texturised 纹理（默认）是描边显露的纹理，如纸张；moving 纹理属于笔尖并随其滚动（海绵、滚筒）。深度0.4–0.7表现为纹理；1只留下峰值。使用 tip.grain 用于工具的纹理，behaviour.grain 用于纸张的纹理。

陷阱

• 宿主拒绝的刻面。 create_brush 拒绝它，update_brush 拒绝添加它的更改，并附带刻面和修复方法；check_brush 返回 degraded，即剥离了这些刻面的画笔，作为起点。
• 在无法绘制所有内容的宿主中调整画笔。 update_brush 保留画笔已为其他宿主拥有的内容（例如从画布更改的绘画画笔的光照），并在 kept 中列出；它不会被剥离。要为此宿主仅制作一份副本，请从 check_brush 的 degraded 画笔创建。
• ID。 内置ID不能重用或更改；已占用的ID会被拒绝（改为更新它）。
• 印章。 任何笔触都可以使用来自 find_stickers 的任何贴纸引用，或编辑器印章（例如 editor:star…）。宿主贴纸库无法加载的引用会被拒绝，并附带最接近的引用。只有绘画编辑器渲染印章笔尖和分散墨点；画布、矢量和图像编辑器拒绝它们（check_brush 会指出）。
• 图像源。 库中没有的 source:<id> 会被拒绝，并附带最接近的ID；先添加它。替换源的图像（overwrite）会更改引用它的每个画笔，但不会更改已绘制的描边。对象笔触仅使用贴纸，因此其中的图像源会被舍弃（problems 会指出）。画笔包通常仅限个人使用：保留与源关联的 licence 文本。
• 画笔包。 仅导入笔尖（以及Procreate纹理）：动态、铅笔曲线、图案、双画笔和湿设置列在 unsupported 中，因此导入的画笔使用默认感觉绘制；调整它们。导入的图像笔尖是印章笔尖，因此画布、矢量和图像编辑器无法绘制它们（renderable 为假）。包通常仅限个人使用：传递并保留其 licence；未经检查，切勿重新分发导入画笔的库文件。
• 超出范围的值 会被模式拒绝（tip.size 为1..2500像素）；存储的画笔在导入时会被钳制，并在 problems 中报告。
• 绘画编辑器从此库绘制。 其 set_brush 按ID从此处选择画笔，并在其上叠加刻面而不保存；create_brush / update_brush 存储画笔。绘画宿主使用其自身的预览注册这些工具（createPaintBrushLibraryToolProvider），因此绘画编辑器没有自己的列表、保存、导出、导入或缩略图工具。

工作流技能

• pixerate-brushes-design：从描述（例如“柔软的粉色荧光笔”、“适合画布的粉笔”）到保存且检查过的画笔。

工具参考

工具	用途
list_brush_presets	查找此宿主渲染的画笔：kind、medium、variety、tool、tag、text、source（全部、内置、用户）、all、offset、limit。返回 brushes（id、名称、内置、种类、介质、变体或工具、类别、引擎、笔尖、尺寸、墨点、表面、光照）和 total。请首先调用。
describe_brush	按 id 描述一个画笔：其完整刻面 brush（含其 colour：默认、调色板、自身）、builtin、engine、category 和此宿主的 check（包括印章贴纸）。未知ID会被拒绝，并附带最接近的ID。
create_brush	保存新画笔：id、name、可选 basedOn 以及刻面，包括 colour（要保留编辑器当前画笔，传入其 get_brush 返回的 brush）。针对此宿主（及其贴纸库，用于印章笔尖）进行规范化并检查；被拒绝的画笔不保存任何内容。返回 id、brush、engine、problems、warnings。
update_brush	修改现有画笔：id 和要更改的刻面（对象合并；列表替换）。对于内置预设返回错误。返回 changed、problems、warnings、kept（宿主无法渲染的内容）。
duplicate_brush	复制画笔（包括内置预设）以赋予新 id，然后像新画笔一样修改。
remove_brush	删除用户画笔。返回成功。
check_brush	检查一个笔刷：brush（完整规格）和 host（可选；否则使用当前宿主）。返回：host、renderable、engine、warnings（渲染时不支持的刻面，附带修复方法）、errors（拒绝它的刻面，附带修复方法）、degraded（剥离了错误刻面的画笔，可作为起点）。对图像源和贴纸引用进行验证。
export_brushes	将画笔写入库文件：ids（数组，最多20个）。返回 libraryFile、fileName。
import_brushes	从库文件添加画笔：libraryFile（base64 字符串，从 export_brushes 获得）。返回 ids（新画笔）和 report（每个已迁移或跳过的画笔）。
import_brush_pack	导入画笔包：file（base64）、fileName、licence（保留随附的文本）。返回 brushes（含此宿主的 renderable）、unsupported、problems、licence。提示用户保留 licence；不要重新分发。
preview_brush	生成画笔的小预览：brush（完整规格）、width 和 height，可选 format（svg、png、webp）、canvas（颜色；如果为null则使用画笔默认值）、colour（绘制该颜色；如果为null则使用画笔默认值）。仅限绘画编辑器。
add_brush_source	添加图像源：id、name、image（base64 PNG）、channel（auto、transparency、dark、light）和 licence。返回 id。
list_brush_sources	列出图像源。返回 sources（id、名称、关联的画笔ID）

注意：此列表为精简版；完整规格请参考原始文档。