Parameters cheatsheet

Here’s a complete list of the parameters you can set from python or the CLI. Notice that for the CLI you can either use the short form (e.g. -i) or the long form (e.g. --input) for the parameter names.

More details are available in the docs, or in the webapp’s help section (along with some tips to ensure good visual quality).

Parameter (API)	CLI flag	Type	Default	Description
img_path	-i, --input	str (path)	Required	Path to input image (.png, .jpg, .jpeg, .pdf). Auto-grayscaled; cropped if circle layout; transparent PNGs filled with background_color.
num_nails	-n, --nails	int	Required	Number of nails on the border. More nails = higher detail but slower. Try increasing it by ~50-100 if circular ring artifacts appear with layout=="circle". Recommended: typical values: 150–400 (don’t go too much lower to ensure good visual quality, don’t go too much higher to ensure good/stable performance).
downscale_factor	-d, --downscale	float	Required	Rescales image before processing to use a lower internal resolution → speed up computations. Lower → faster, coarser; higher → slower, sharper. Recommended: choose a value that causes your pic to go down to ~300-700px per side. Typical values: 0.25-0.5 (to halve or more pic size). Try increasing this if output visual quality is too low or if the algorithm stops too early compared to the input maxiter.
string_strength	-s, --strength	float	0.1	How much each line darkens the canvas. Higher → darker, thicker effect. Recommended: increase this if final image appears too white/empty, decrease if too dark/filled in. Typical values: 0.1-0.25 (don’t go too much higher than this or the output will be a black mess).
max_num_iter	-ni, --maxiter	int	5000	Maximum number of strings/iterations. Larger = more detail, slower. Early stopping may stop earlier.
nail_layout	-l, --layout	str	"circle"	Nail arrangement: "circle" or "rectangle". Circle recommended.
cache_lines	-nc, --no-cache	bool flag	True (API), False (CLI)	Cache line computations for speed. Recommended: disable caching only for debugging, i.e. always use the default values, unless you really want num_nails larger than ~800 and don’t have enough RAM.
precache_lines	-npc, --no-precache	bool flag	True (API), False (CLI)	Precompute all line paths before starting (much faster at runtime, uses more memory). Recommended: leave precaching on, i.e. always use the default values, unless you really want num_nails larger than ~800 and don’t have enough RAM.
min_angle_diff	-mad, --min-angle-diff	float	π/8 (≈0.39)	Circle layout only. Minimum angular spacing (radians) between consecutive nails to avoid redundant/parallel lines.
background_color	-bc, --background-color	tuple[int,int,int]	(50, 50, 50)	RGB color (0–255). Used to replace transparency in PNGs.
patience	-p, --patience	int	20	Early stopping patience: number of stagnant iterations before halting.
epsilon	-e, --epsilon	float	1e-6	Early stopping tolerance: minimum error improvement considered significant.
(output path)	-o, --output	str (path)	None	Where to save the generated image. Folder or file. Extensions: .png, .jpg, .jpeg, .pdf.
(string order)	-so, --string_order	str (path)	None	Save nail sequence to file (.txt).
(distance vec)	-ds, --distance	str (path)	None	Save error progression to file (.txt).