# 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`).                                                                                                             |