Перейти до вмісту
Hokusai2.2.2
ivantokar.com

Згенерований текст

Hokusai відтворює текст через libvips і Pango. Hokusai.text(_:layout:style:) повертає звичайний незмінний конвеєр (прозоре зображення тексту), який можна перетворювати, накладати чи кодувати окремо; drawText — скорочення для накладання цього конвеєра на наявний. Для відтворення тексту потрібна libvips, зібрана з Pango (Hokusai.capabilities().textRendering), а збірка без неї повідомляє HokusaiError.unsupported із завершальної операції, а не з виклику.

TextLayout задає розмір текстового блока:

  • .natural (типово): такого розміру, якого потребує текст; рядки розриваються лише на переносах.
  • .width(_:wrap:): переносить рядки за шириною в пікселях за розміру шрифту й DPI стилю. wrap — .word (типово), .character, .wordCharacter (розрив між словами та всередині надто довгого слова) або .none.
  • .fit(width:height:): найбільша роздільність, за якої текст вміщується в блок. dpi стилю не використовується, а lineHeight має лишатися 1.
let style = TextStyle(fontSize: 40, color: Color(red: 0.1, green: 0.14, blue: 0.3))
let sentence: TextContent = "The lighthouse keeper wound the clock every evening."
// natural: as large as the text needs; lines break only at newlines.
let natural = try Hokusai.text(sentence, style: style)
// width: wrap lines to a pixel width.
let wrapped = try Hokusai.text(sentence, layout: .width(420), style: style)
// width with .character breaks anywhere, `.none` never breaks and clips at the width.
let clipped = try Hokusai.text(sentence, layout: .width(420, wrap: .none), style: style)
// fit: the largest size that fits the box (the style's dpi is not used).
let fitted = try Hokusai.text(sentence, layout: .fit(width: 420, height: 120), style: style)
for (name, text) in [("natural", natural), ("wrapped", wrapped), ("clipped", clipped), ("fitted", fitted)] {
try await text.png().write(to: URL(fileURLWithPath: "\(name).png"))
}
  • Речення в один довгий рядок, 954 на 38 пікселів.
    .naturalPNG · 954 × 38 · 8 KB
  • Речення, перенесене на три рядки, 393 на 120 пікселів.
    .width(420)PNG · 393 × 120 · 11 KB
  • Речення знову в один рядок; перенесення не відбулося.
    .width(420, wrap: .none)PNG · 954 × 38 · 8 KB
  • Речення, вписане в блок 420 на 120, три рядки, 393 на 120 пікселів.
    .fit(420 × 120)PNG · 393 × 120 · 11 KB

Виміряні розміри наведено в кожному підписі. Зверніть увагу, що .width(420) дав зображення завширшки 393 пікселі, бо рядки розірвалися до досягнення межі, а wrap: .none у цій збірці поводився як .natural (954 × 38), тож не покладайтеся на нього для обрізання тексту; обрізайте через extract, якщо потрібно.

Властивість Тип За замовчуванням Межі
font String "sans" Родина й стиль Pango без розміру, напр. "Helvetica Bold"; не шлях до файлу.
fontFile URL? nil Локальний файл TTF чи OTF, доступний для font на цей рендер. Потребує libvips із fontconfig; файл, який libvips не може завантажити, — лише попередження, і використовується названий font.
fontSize Int 24 1…2000 пунктів за dpi.
color Color чорний
alignment TextAlignment .left .left, .center, .right.
justify Bool false Розтягує перенесені рядки на повну ширину.
lineHeight Double 1 0.5…5, кратне природній висоті рядка шрифту.
dpi Int 72 1…2400; ігнорується в .fit.
stroke TextStroke? nil Обведення: color, width у (0, 64].
shadow TextShadow? nil offsetX/offsetY у межах ±10 000, blur 0…64 (типово 1.2), color (його непрозорість — це непрозорість тіні).
rotation Double 0 Градуси за годинниковою стрілкою; скінченне.
let base = TextStyle(font: "sans Bold", fontSize: 72, color: Color(red: 0.1, green: 0.14, blue: 0.3))
var stroked = base
stroked.color = .white
stroked.stroke = TextStroke(color: Color(red: 0.1, green: 0.14, blue: 0.3), width: 4)
var shadowed = base
shadowed.shadow = TextShadow(offsetX: 4, offsetY: 4, blur: 3)
var rotated = base
rotated.rotation = -12
let variants: [(String, TextStyle)] = [("plain", base), ("stroke", stroked), ("shadow", shadowed), ("rotated", rotated)]
for (name, style) in variants {
try await Hokusai.text("Hokusai", style: style).png().write(to: URL(fileURLWithPath: "\(name).png"))
}
// Alignment and line height apply to multi-line text.
var centred = TextStyle(fontSize: 36, color: Color(red: 0.1, green: 0.14, blue: 0.3))
centred.alignment = .center
centred.lineHeight = 1.4
try await Hokusai.text("Hokusai\nSwift image processing", style: centred).png()
.write(to: URL(fileURLWithPath: "centred.png"))
  • Слово Hokusai темно-синім жирним шрифтом.
    звичайнийPNG · 270 × 55 · 4 KB
  • Білі літери з темно-синім контуром.
    обведенняPNG · 278 × 63 · 9 KB
  • Темно-сині літери з м’якою тінню праворуч донизу.
    тіньPNG · 290 × 75 · 12 KB
  • Слово, нахилене на дванадцять градусів проти годинникової стрілки, на більшому полотні.
    обертання −12PNG · 276 × 110 · 11 KB
  • Два рядки по центру: Hokusai над Swift image processing, з просторим міжрядковим інтервалом.
    по центру, lineHeight 1.4PNG · 367 × 86 · 7 KB

Шрифти надходять із хоста: установіть потрібні застосунку й вказуйте ім’я встановленої родини. Постачайте шрифти разом із застосунком і завантажуйте через fontFile, коли хост неможливо контролювати.

TextContent — це .plain(String) або .markup(String); рядковий літерал є звичайним. Звичайний текст завжди екранується, тож будь-який рядок користувача безпечно відтворювати. .markup — це розмітка Pango (не HTML і не CSS) для змішаних шрифтів, розмірів і кольорів; хибна розмітка викликає помилку під час відтворення тексту.

// Pango markup mixes fonts, sizes and colours in one text. (Plain text is always escaped.)
let markup = """
<span size="xx-large" weight="bold">Sale</span> <span foreground="#c83030">−30%</span>
<i>this week only</i> · <span font_family="monospace">code HOKUSAI</span>
"""
try await Hokusai.text(.markup(markup), style: TextStyle(fontSize: 36, color: Color(red: 0.1, green: 0.14, blue: 0.3)))
.png().write(to: URL(fileURLWithPath: "markup.png"))
// Characters that look like markup are safe in plain text.
try await Hokusai.text(.plain("a < b & c"), style: TextStyle(fontSize: 36, color: Color(red: 0.1, green: 0.14, blue: 0.3)))
.png().write(to: URL(fileURLWithPath: "plain-escaped.png"))
  • Sale великим жирним, мінус 30 відсотків червоним, потім курсив і моноширинний текст у другому рядку.
    розміткаPNG · 515 × 104 · 12 KB
  • Текст a менше b і c, відтворений буквально.
    звичайний, екранованийPNG · 142 × 27 · 2 KB

Малювання на зображенні

Section titled “Малювання на зображенні”

drawText(_:placement:layout:style:) накладає відтворений текст за тими самими правилами розміщення, обрізання й змішування, що й будь-який інший шар (Композиція). placement — це .at(x:y:) або .gravity(_:offsetX:offsetY:).

let photo = try Hokusai(url: URL(fileURLWithPath: "scene.png")).resize(width: 640)
var style = TextStyle(font: "sans Bold", fontSize: 40, color: .white)
style.shadow = TextShadow(offsetX: 2, offsetY: 2, blur: 2, color: Color(red: 0, green: 0, blue: 0, opacity: 0.7))
try await photo
.drawText("Pharos Point", placement: .gravity(.southWest, offsetX: 24, offsetY: 20), style: style)
.webp(quality: 88)
.write(to: URL(fileURLWithPath: "caption.webp"))
  • Пейзаж із білим підписом Pharos Point та м’якою тінню в нижньому лівому куті.
    drawTextWEBP · 640 × 400 · 15 KB
func attempt(_ name: String, _ build: () throws -> Hokusai) async {
do {
let output = try await build().png().data()
print(name, "→", output.info.width, "×", output.info.height)
} catch {
print(name, "→ throws", error)
}
}
let style = TextStyle(fontSize: 24)
await attempt("hello") { try Hokusai.text("Hello", style: style) }
await attempt("empty text") { try Hokusai.text("", style: style) }
await attempt("font file as family") { try Hokusai.text("Hi", style: TextStyle(font: "/fonts/Inter.ttf")) }
await attempt("fontSize 3000") { try Hokusai.text("Hi", style: TextStyle(fontSize: 3000)) }
await attempt("fit with lineHeight") {
var tall = TextStyle(); tall.lineHeight = 2
return try Hokusai.text("Hi", layout: .fit(width: 200, height: 100), style: tall)
}
await attempt("invalid markup") { try Hokusai.text(.markup("<b>unclosed"), style: style) }
Виклик Результат
Hokusai.text("Hello", style: TextStyle(fontSize: 24)) зображення 52 × 19
порожній текст invalidOption(name: "text", …"must not be empty")
font, що є шляхом (/fonts/Inter.ttf) invalidOption(name: "font", …"is a family name; pass a font file as fontFile")
fontSize: 3000 invalidOption: «must be from 1 through 2000»
.fit з lineHeight, відмінним від 1 invalidOption: «must be 1 with a fit layout»
хибна розмітка invalidInput: «the text is not valid Pango markup»