筆刷
筆刷由多個面向組成，這些面向定義了筆刷的性質與行為，而非由哪個繪圖引擎繪製。
只有 id、name、kind 和 tip.shape 是必填的；其他所有欄位都會繼承面向所選引擎的預設值，因此筆刷只儲存使其成為自身的獨特設定。筆刷庫中保存了內建預設集（唯讀）和所有使用者建立的筆刷，所有可繪圖的編輯器皆可共享。
| 面向 (欄位) | 說明 |
|---|---|
| 種類 (Kind) | mark 用來塗佈顏料；tool 則作用於已繪製的顏料上。 |
| 媒介與變化 (Medium and variety) | 筆跡 (Marks)：塗佈的物質 (paint、ink、dry、spray) 及其種類 (oil、watercolor、gouache、pencil、charcoal、airbrush、marker、highlighter…)。這些是描述性的，用於尋找筆刷；變化為 watercolor、gouache 或 oil 的濕筆刷會以該媒介繪製。 |
| 工具 (Tool) | 工具：eraser、blender、smudge，以及作用於濕顏料上的 water、dryer、blow、blot、wet-blend、wet-drag。 |
| 筆尖 (Tip) | shape (round、flat、chisel 是由 roundness 和 angle 設定的橢圓；bristle 有刷毛；stamp 採用 stamps 的形狀：一個編輯器印章 editor:star、來自 find_stickers 的任何貼紙引用，或來自 list_brush_sources 的圖片來源 source:<id>)，大小（px），硬度（圖片筆尖在數值低於 1 時，邊緣會逐漸淡出），間距，不透明度，流量，混合模式，以及 grain：每個筆跡內部的紋理（source：一種圖案，如 rough、canvas、sanded，或 source:<id>；mode texturised 會固定在畫布上，moving 則會隨筆尖滾動；scale、depth、contrast、invert）。 |
| 筆跡 (Marks) | continuous 筆跡（預設；對於印章筆尖，每個筆跡都是第一個印章的形狀，使用顏料顏色），scatter（噴灑：筆尖上的小墨滴，具 density、size），particles（股、彈簧、絲帶、火花；來自印章的紋理點），或 objects（每個筆跡都是一個可編輯的貼紙，使用其自身的顏色）。 |
| 動態 (Dynamics) | 筆觸感應：壓力對應大小和不透明度，平滑、傾斜、速度、抖動（sizeJitter、angleJitter 用於旋轉、opacityJitter、scatter）、旋轉、count（每個間距步長的筆跡數量，每個都經抖動）和 flip（隨機鏡像筆跡：x、y、xy）。 |
| 行為 (Behaviour) | surface dry、wet（濕顏料設定）或 thick（厚塗設定）；紙張 grain；exchange（顏料吸取與混合；reservoir 可製成混色筆刷）；工具 strength。 |
| 光照 (Light) | 筆刷發出的光線（amount），以及建議的圖層 spill 和 glow。 |
| 動畫 (Motion) | 繪製後的動畫（即時特效繪畫、粒子 waveSpeed）。 |
| 顏色 (Colour) | 一個 default 顏色、一個最多 16 色的 palette，或 own（永遠使用自身顏色）。每個顏色可以是十六進位或 rgba() 顏色、一個亮色/暗色組合 { light, dark }、一個漸層或特效顏料。漸層預設值總是會被繪製；固色或亮/暗預設值會在選取筆刷時成為編輯器的顏色（除非使用者鎖定了自己的顏色），並根據色彩配置進行解析。畫布筆觸和向量筆刷筆觸在未指定顏色時也會採用此顏色。畫布和向量具有相同的鎖定機制（canvas.setColorLocked、vector.setColorLocked），從亮/暗預設值取得的畫布顏色會像繪圖編輯器一樣跟隨色彩配置；已繪製的向量筆觸則保留其原有顏色。 |
媒介如何對應到面向：鉛筆或木炭是 dry，具有高 grain 和傾斜；墨水是堅硬的圓形筆尖，壓力控制大小（鋼筆會因速度而變細）；水彩和濕油畫是在 surface: 'wet' 上的 paint；厚塗是 surface: 'thick'；噴槍是 spray，柔和且流量低；噴漆罐是帶有 marks 分散效果的 spray；原子筆、凝膠筆或代針筆是帶有小型硬筆尖的 ink（代針筆無壓力控制大小）；蠟筆和粉筆是帶有高 grain 的 dry；螢光筆是 ink / highlighter，為相乘模式的斜角筆尖，帶有少量光照，spill 半徑為 0，預設為螢光黃色；印章筆刷是具有連續筆跡的 stamp 筆尖；粒子和貼紙筆刷是在 stamp 筆尖上的 marks 粒子或物件。圖片筆刷（掃描的木炭筆跡、樹葉、乾筆刷紋理）是印章為圖片來源的 stamp 筆尖，通常帶有 tip.grain、angleJitter、flip 和少量的 scatter，以避免重複圖案明顯。
圖片來源是製作筆尖和紋理所需的圖片，儲存在筆刷庫中，包含其位元組（灰色遮罩，最長 512 px）及其授權。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 會顯示該主機的筆刷。人們可以在任何主機中使用相同的筆刷編輯器來編輯筆刷，其範圍界定方式相同：它只顯示主機使用的控制項（畫布上無速度，影像編輯器中無紋理），並會保留筆刷為其他主機設定的內容。工具遵循相同的規則（請參閱陷阱）。
用於畫布或向量筆觸的已儲存筆刷會被複製到筆觸中，因此文件在缺少筆刷庫時仍能正確渲染；之後在筆刷庫中更改筆刷，不會改變已繪製的筆觸。
工作方法
- 尋找最接近的筆刷。 使用
list_brush_presets搭配medium、variety、kind或text。它只會列出此主機可渲染的項目（all: true會列出其餘項目並標示renderable）。 - 讀取它。 使用
describe_brush取得完整的規格、其解析出的引擎及其檢查結果。 - 製作筆刷。 使用
create_brush，指定一個新的id、name、basedOn最接近的預設集，以及僅需更改的面向（物件會合併；列表會取代）。讀取problems（被限制或捨棄的值）和warnings。主機無法渲染的筆刷將會被拒絕，且不會儲存任何內容。 - 查看它。 當主機有渲染器時使用
preview_brush；否則在編輯器中繪製測試筆觸（先使用新的 id 呼叫set_brush，再呼叫paint_stroke）。 - 調整它。 使用
update_brush搭配要更改的面向，或使用unset來移除整個面向。它會回傳已changed的路徑。內建預設集無法更改：請先使用duplicate_brush。 - 從圖片製作。 使用
add_brush_source搭配 PNG（當auto選錯部分時使用channel；保留其附帶的licence），然後使用tip: { shape: "stamp", stamps: ["source:<id>"] }建立筆刷作為圖片筆尖，或使用tip.grain.source作為紋理。list_brush_sources會列出它們以及哪些筆刷使用了每個來源。 - 匯入套件。 使用
import_brush_pack搭配檔案（base64）、其fileName和隨附的licence。讀取brushes（帶有此主機的renderable）、unsupported（未映射的內容）和licence，然後使用preview_brush預覽幾個，並使用update_brush調整它們。 - 分享它。 使用
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筆刷來create_brush。 - ID。 內建 ID 不能重複使用或更改；已被佔用的 ID 會被拒絕（請改用 update）。
- 印章。 任何筆跡都可以使用來自
find_stickers的任何貼紙引用，或編輯器印章（editor:star…）。主機的貼紙庫無法載入的引用會被拒絕，並提供最接近的引用。只有繪圖編輯器能渲染印章筆尖和分散筆跡；畫布、向量和影像編輯器會拒絕它們（check_brush會指出）。 - 圖片來源。 庫中沒有的
source:<id>會被拒絕，並提供最接近的 ID；請先新增它。替換來源的圖片（overwrite）會更改所有使用它的筆刷，但不會更改已繪製的筆觸。物件筆跡只接受貼紙，因此其中的圖片來源會被捨棄（problems會指出）。筆刷套件通常僅授權個人使用：請保留來源的licence文字。 - 筆刷套件。 僅匯入筆尖（以及 Procreate 的紋理）：動態、鉛筆曲線、圖案、雙筆刷和濕顏料設定會在
unsupported中列出，因此匯入的筆刷會使用預設的觸感繪製；請調整它們。匯入的圖片筆尖是印章筆尖，因此畫布、向量和影像編輯器無法繪製它們（renderable為 false）。套件通常僅供個人使用：請傳遞並保留其licence；未經檢查，切勿重新分發包含匯入筆刷的庫檔案。 - 超出範圍的值 會被架構拒絕（
tip.size範圍為 1..2500 px）；儲存的筆刷在匯入時會被限制，並在problems中報告。 - 繪圖編輯器從此庫中繪製。 其
set_brush會根據此處的 ID 選取筆刷，並在其上疊加面向而不儲存；create_brush/update_brush則會儲存一個。繪圖主機會使用自己的預覽註冊這些工具（createPaintBrushLibraryToolProvider），因此繪圖編輯器本身沒有自己的列表、儲存、匯出、匯入或縮圖工具。
工作流程技能
pixerate-brushes-design：從描述（「一支柔和的粉色螢光筆」、「用於畫布的粉筆」）到一個已儲存、已檢查的筆刷。
工具參考
| 工具 | 用途 |
|---|---|
list_brush_presets | 尋找此主機可渲染的筆刷：kind、medium、variety、tool、tag、text、source (all, builtin, user)、all、offset、limit。回傳 brushes (id, name, builtin, kind, medium, variety or tool, category, engine, tip, size, marks, surface, light) 和 total。請先呼叫。 |
describe_brush | 依據 id 取得單一筆刷：其完整面向 brush（包含其 colour：default, palette, own）、builtin、engine、category，以及此主機的 check（包含印章貼紙）。未知 ID 會被拒絕，並提供最接近的 ID。 |
create_brush | 儲存新筆刷：id、name、可選的 basedOn，以及面向，包含 colour（若要保留編輯器目前的筆刷，請傳入其 get_brush 回傳的 brush）。會針對此主機進行標準化和檢查（以及其貼紙庫，用於印章筆尖）；被拒絕的筆刷不會儲存任何內容。回傳 id、brush、engine、problems、warnings。 |
update_brush | 更新現有筆刷的面向：id，以及要更改的面向。使用 unset 移除整個分支（例如 colour）；內建筆刷無法更新（請先複製）。回傳 changed、brush、engine、problems、warnings、kept。 |
duplicate_brush | 複製筆刷為一個新的 id 和 name。回傳 id、brush、engine、problems、warnings。 |
remove_brush | 從庫中移除使用者筆刷，依據 id。內建筆刷無法移除。回傳 removed。 |
check_brush | 在一個主機上檢查筆刷：id、host（paint, image, canvas, vector）。回傳 errors（拒絕並附修正）、warnings（不支援但不會遺失），以及 degraded（該主機可渲染的筆刷）。使用 check_brush 的 degraded 作為 create_brush 的基礎，以製作僅限該主機的副本。 |
export_brushes | 寫入一個庫檔案：ids（要包含的筆刷），以及可選的 name 和 description。預設會包含所有使用中的圖片來源以及整個庫。一個庫檔案是一個 .pixerate-brush 檔案。 |
import_brushes | 從 file（base64）新增一個庫檔案中的筆刷。回傳 imported、ignored、problems、upgraded。 |
import_brush_pack | 從 file（base64）、fileName 和 licence 匯入。回傳 brushes（renderable）、unsupported、licence。 |
preview_brush | 產生一個筆刷預覽，依據 id、可選的 size 和 stroke。回傳 thumbnail（base64）。 |
add_brush_source | 新增一個圖片來源：source（base64）、channel（auto, mask, dark, light）、licence。回傳 id 和 metadata。 |
list_brush_sources | 列出圖片來源：可選的 brushId 用於查找使用中的來源。回傳 sources（id, name, size, licence, usedBy）。 |