PaperSketchEffectLib — Plan9Basic Documentation

Overview

PaperSketchEffectLib transforms an image to look like a pencil sketch on paper, wrapping the FireMonkey TPaperSketchEffect component. The effect extracts edges and renders them as hand-drawn strokes against a light background, creating an artistic sketch appearance with adjustable brush size.

Property	Details
Library	`PaperSketchEffectLib`
Prefix	`papersketch_`
Wraps	`TPaperSketchEffect`
Functions	12
Type	Visual effect (artistic)

Category	Count	Description
Creation / Destruction	2	Create and free effect
Brush Size	2	Get/set stroke thickness
Effect Control	4	Enabled and trigger get/set
Error Handling	4	Error codes and messages

✏ Artistic Filter: This effect is perfect for creating sketch-style art from photographs, building "before and after" comparisons, or adding an artistic touch to image galleries in your applets.

PaperSketch vs PencilStroke

Plan9Basic offers two similar sketch effects. Both use a BrushSize property, but produce different visual results:

Feature	PaperSketch	PencilStroke
Visual style	Pencil on paper — lighter, softer	Bold pencil strokes — darker, more defined
Background	Light paper-like appearance	Darker, more contrast
Edge detection	Softer edges	Sharper, more pronounced edges
Best for	Soft sketches, watercolor feel	Bold drawings, comic-style art
Parameters	BrushSize only	BrushSize only

Cross-Platform Support

Platform	Support
Windows	✅ Full support
Linux	✅ Full support
Android	✅ Full support

Creation & Destruction

papersketch#(parent#)

Creates a new paper sketch effect attached to the specified visual control.

Parameter	Type	Description
`parent#`	Pointer	Target visual control (e.g., image)
Returns	Pointer	Effect handle, or 0 on failure

papersketch_free(effect#)

Destroys the effect and releases associated resources.

╯ create-sketch.bas─◻✕
let sketch# = papersketch#(img#)
papersketch_brushsize#(sketch#, 1.5)

' Clean up when done
papersketch_free(sketch#)

Error Handling

Function	Signature	Description
`papersketch_error()`	`papersketch_error@`	Returns last error code (0 = none)
`papersketch_errormsg$()`	`papersketch_errormsg$@`	Returns last error message
`papersketch_strerror$(code)`	`papersketch_strerror$@n`	Converts error code to text
`papersketch_clearerror()`	`papersketch_clearerror@`	Clears the error state

Brush Size

Controls the thickness of the sketch strokes. Smaller values produce finer, more detailed sketches; larger values create bolder, more pronounced strokes.

Function	Signature	Description
`papersketch_brushsize#(effect#, value)`	`papersketch_brushsize#@#n`	Sets brush/stroke size
`papersketch_brushsize(effect#)`	`papersketch_brushsize@#`	Gets brush size

Value	Description	Use Case
`0.1–0.5`	Very fine strokes	Detailed, delicate sketches
`0.5–1.0`	Fine to medium strokes	General purpose sketching
`1.0–2.0`	Medium strokes (default range)	Balanced sketch appearance
`2.0–5.0`	Bold strokes	Pronounced, artistic look

Effect Control

Function	Signature	Description
`papersketch_enabled#(effect#, value)`	`papersketch_enabled#@#n`	Enable (1) or disable (0)
`papersketch_enabled(effect#)`	`papersketch_enabled@#`	Gets enabled state
`papersketch_trigger#(effect#, trigger$)`	`papersketch_trigger#@#$`	Sets trigger string
`papersketch_trigger$(effect#)`	`papersketch_trigger$@#`	Gets trigger string

Complete Examples

Example 1: Basic Paper Sketch

╯ basic-sketch.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let sketch# = Pointer#(0)

frm# = form#("Paper Sketch Demo", 400, 350)

img# = image#(frm#)
image_bounds#(img#, 100, 30, 200, 150)
image_load#(img#, "https://picsum.photos/200/150")

' Apply paper sketch effect
sketch# = papersketch#(img#)
papersketch_brushsize#(sketch#, 1)

form_show(frm#)

Example 2: Adjustable Brush Size

╯ adjustable-sketch.bas─◻✕
let frm# = Pointer#(0)
let img# = Pointer#(0)
let sketch# = Pointer#(0)
let trkBrush# = Pointer#(0)
let lblBrush# = Pointer#(0)

frm# = form#("Sketch Brush Control", 450, 400)

img# = image#(frm#)
image_bounds#(img#, 125, 30, 200, 150)
image_load#(img#, "https://picsum.photos/200/150")

sketch# = papersketch#(img#)
papersketch_brushsize#(sketch#, 1)

' Brush size slider
lblBrush# = label#(frm#, "Brush Size: 1.0", 160, 200)
trkBrush# = trackbar#(frm#)
trackbar_bounds#(trkBrush#, 50, 230, 350, 30)
trackbar_max#(trkBrush#, 50)
trackbar_value#(trkBrush#, 10)
trackbar_onchange#(trkBrush#, "OnBrushChange")

form_show(frm#)

function OnBrushChange(sender#) local b
  let b = trackbar_value(trkBrush#) / 10
  if b < 0.1 then
    b = 0.1
  endif
  papersketch_brushsize#(sketch#, b)
  label_text#(lblBrush#, "Brush Size: " + stri$(b, 1))
endfunction

Example 3: Compare Original and Sketch

╯ sketch-comparison.bas─◻✕
let frm# = Pointer#(0)
let img1# = Pointer#(0)
let img2# = Pointer#(0)
let sketch# = Pointer#(0)

frm# = form#("Sketch Comparison", 500, 350)

' Original image
img1# = image#(frm#)
image_bounds#(img1#, 50, 30, 180, 135)
image_load#(img1#, "https://picsum.photos/180/135")
let lbl1# = label#(frm#, "Original", 110, 175)

' Paper sketch version
img2# = image#(frm#)
image_bounds#(img2#, 270, 30, 180, 135)
image_load#(img2#, "https://picsum.photos/180/135")
sketch# = papersketch#(img2#)
papersketch_brushsize#(sketch#, 1.5)
let lbl2# = label#(frm#, "Paper Sketch", 310, 175)

form_show(frm#)

Best Practices

Practice	Why
Use images with clear edges and contrast	Edge detection works best with well-defined features
Start with BrushSize 1.0	Good default — adjust up for bolder strokes, down for finer detail
Clamp minimum to 0.1	Very small values may produce minimal visible effect
Combine with Monochrome for pre-processing	Convert to grayscale first for consistent sketch results
Use side-by-side comparisons	Show original and sketch together for maximum visual impact

Quick Reference

Function	Signature	Description
CREATION & DESTRUCTION
`papersketch#(parent#)`	`papersketch#@#`	Create effect
`papersketch_free(effect#)`	`papersketch_free@#`	Destroy effect
BRUSH SIZE
`papersketch_brushsize#(effect#, value)`	`papersketch_brushsize#@#n`	Set brush size
`papersketch_brushsize(effect#)`	`papersketch_brushsize@#`	Get brush size
EFFECT CONTROL
`papersketch_enabled#(effect#, value)`	`papersketch_enabled#@#n`	Enable/disable
`papersketch_enabled(effect#)`	`papersketch_enabled@#`	Get enabled state
`papersketch_trigger#(effect#, trigger$)`	`papersketch_trigger#@#$`	Set trigger
`papersketch_trigger$(effect#)`	`papersketch_trigger$@#`	Get trigger
ERROR HANDLING
`papersketch_error()`	`papersketch_error@`	Last error code
`papersketch_errormsg$()`	`papersketch_errormsg$@`	Last error message
`papersketch_strerror$(code)`	`papersketch_strerror$@n`	Code to text
`papersketch_clearerror()`	`papersketch_clearerror@`	Clear error state

Library	Description
`PencilStrokeEffectLib`	Bold pencil stroke effect
`EmbossEffectLib`	3D embossed look
`MonochromeEffectLib`	Grayscale conversion
`ToonEffectLib`	Cartoon/cel-shaded effect