BitmapTracer

1. About BitmapTracer

BitmapTracer automatically converts raster graphics (bitmaps) into scalable vector graphics. The program detects contours and generates precise vector paths for lossless printing at any size.

Feature	Details
Input formats	BMP, PNG, JPG/JPEG, TIFF, GIF, WebP
Output formats	SVG, PDF, DXF, PNG
Engines	OpenCV (built-in) + potrace (external, optional)
Operating system	Windows 10 / 11 (64-bit)
Author	Bernhard Lickert · Developed with Claude (Anthropic)

2. Installation & Launch

Contents of the EXE folder (dist\)

After building, the dist\ folder contains the EXE. The following files must be placed beside the EXE:

File	Required	Notes
BitmapTracer_v1.10.6.exe	✓	The application
potrace.exe	recommended	Embedded in EXE from v1.10.5 (fallback). A file beside the EXE takes priority and allows updates without rebuilding. Download: potrace.sourceforge.net
bt_profiles.json	optional	Embedded from v1.10.5. Created beside the EXE once profiles are saved (then takes priority over embedded copy).
bt_5_Farben.json	optional	Embedded from v1.10.5. Colour profile supplement.
bt_config.json	–	Created automatically on first launch (user settings, window size, language).
start_bitmap_tracer.bat	optional	Launches EXE or Python directly, clears cache.

3. Operation

Window layout

Area	Function
Header / left panel	Profile management, engine selection, all parameters
Left column	Mode, preprocessing, contrast/levels
Right column	Contour, colors, stencil, export & scale
Toolbar	Open image · Re-trace · Zoom 1:1 · Preview quality · Original on/off
File menu	Open · Export · MRU list (last 5 files) · Quit
Left preview	Original image
Right preview	Tracing result (live update)
Color palette bar	Below the tracing result: color swatches with hex code. Click = on/off, click hex = copy, right-click = change color
Status bar	Engine, contour counter, threshold · progress bar on the right while tracing

Using the sliders

Action	Function
Drag	Set a rough value
Mouse wheel	Fine ±1 step
Shift + mouse wheel	Coarse ±10 steps
Double-click the number	Type an exact value directly
Hover over slider / combo	Tooltip with value range, effect, and ⚠ note
Ctrl+Z / Ctrl+Y	Undo / Redo (up to 20 steps)

Using the preview

Action	Function
Mouse wheel on preview	Zoom towards the cursor position – original and result stay in sync
Left-click + drag	Move the image (pan) – grab cursor appears
Middle-click + drag	Move the image (alternative pan method)
⊞ Zoom 1:1	Reset zoom and pan
Zoom % display (toolbar)	Current zoom factor (100% = fit)

4. Color Palette Bar

After a color trace (mode = color, OpenCV engine) a bar appears below the tracing result with one swatch per k-means color layer.

Each swatch shows a color block (with eye symbol ●/○) and next to it the hex code of the color (e. g. #3a2f1c).

Action	Effect
Left-click the color block (●)	Show/hide the layer (● = visible, ○ = hidden). Preview updates immediately.
Left-click the hex code	Copy the hex value (e. g. #3a2f1c) to the clipboard. The status bar confirms.
Right-click a swatch	Open the color picker – change this layer's color. Preview updates immediately.
✓ all button	Show all hidden layers again.

5. Zoom & Pan (v1.8.3)

Original and result previews are always synchronized – both show the same section at the same zoom factor.

The mouse wheel zooms towards the cursor position (not the canvas center). Zoom right onto the detail you want to compare – both images remain perfectly aligned.

6. MRU List & Export Path Memory (v1.8.0)

MRU list (Most Recently Used)

The last 5 opened images automatically appear at the end of the File menu. One click opens the image directly – no folder browsing required.

The MRU list is stored in bt_config.json and survives program restarts.

Export path memory

The most recently used export folder is also stored in bt_config.json. On the next export (SVG, PDF, DXF, PNG) the file dialog opens in that folder automatically.

7. Engines

Engine	Strengths	When to use
OpenCV	Always available, color tracing, Canny edges	Logos, color vectorization, line drawings
potrace	Smoothest curves, best grain for photos, Inkscape quality	Portraits, fine grain, stencils from photos

8. Settings Reference

Mode / parameters (OpenCV)

Mode	Description	Suitable for
mono	Black/white tracing, single threshold	Logos, stamps, lettering
color	k-means color quantization, one layer per color	Multicolor logos, clip art
canny	Edge detection, outlines only	Photos → line drawings

Preprocessing

Filter	Description	Tip
none	No preprocessing	For an Inkscape-like result
dither	Floyd-Steinberg dithering → fine organic grain. Threshold internally always 128.	Gamma controls dot density
bayer	Ordered dithering, regular raster. Bayer grain controls raster size (power of 2: 2/4/8/16).	Geometric grain
halftone	Round raster dots like offset printing. Halftone slider controls dot size.	Print look
clahe	Local contrast enhancement. CLAHE limit controls strength.	Poor lighting, scans
bilateral	Preserve edges, reduce noise. Bilateral σ controls strength.	Noisy photos

Contrast / Levels

Parameter	Effect
Input black / white	Black point and white point of the input image
Gamma	Midtone brightness. < 1 = darken (more grain), 1.0 = neutral, > 1 = brighten (less grain). Mouse wheel = ±0.05, Shift+wheel = ±0.5
Output black / white	Contrast limiting of the output

potrace parameters

Parameter	Range	Effect
Threshold	0–255	Binarization threshold. Inkscape default: 126. Ignored when dithering (internally 128).
Alphamax	0.0–1.34	Curve smoothing. 0.0 = pure polygons (maximum grain, but staircase edges on diagonals). 0.5 = compromise. 1.0 = smooth curves (Inkscape default). See also the staircase section.
Opttolerance	0.0–5.0	Path simplification. Inkscape value: 2.632. Higher = smoother, more simplified.

9. Tooltips (v1.8.4)

All settings (sliders, checkboxes, combos, color inputs) have tooltips. Just hover the mouse over an element for 1–2 seconds.

Tooltips explain three things:

• What the setting does
• Which values are sensible (with example values)
• ⚠ When the setting has no effect, e. g. "⚠ ONLY active with filter=bayer. NO EFFECT with other filters."

10. Reset Buttons (v1.8.5)

Three reset buttons restore all values of a section to the standard defaults and immediately trigger a new trace:

Button	Resets
Reset levels	Input black/white · gamma · output black/white
Reset preprocessing	Filter=none · CLAHE limit=2.0 · Bilateral σ=75 · Bayer grain=8 · Halftone=4 · Gaussian blur=0
Reset contour	Approx=smooth · Bézier=✓ · Holes=✓ · Smoothing=0 · Corner angle=70° · Min area=20 · Max area=0

11. Fine Grain Setup

Fine grain means: gray tones are rendered as dot density, like in newspaper or screen printing. The darker a gray tone, the denser the dot pattern.

Method 1: Without dithering (Inkscape style)

Potrace directly on the original image – this is how Inkscape works too.

Parameter	Value	Explanation
Engine	potrace	–
Filter	none	No dithering
Threshold	100–130	Inkscape uses 126
Alphamax	0.0–0.1	As angular as possible = more detail
Opttolerance	2.0–3.0	Same as Inkscape
Min area	1–5	Trace even tiny dots
Gamma	1.0–1.3	Darken slightly for more dots

→ The "Inkscape-Korn" profile contains exactly these settings.

Method 2: Floyd-Steinberg dithering

Floyd-Steinberg distributes the quantization error to neighboring pixels and creates an organic, irregular dot pattern. The FS threshold is internally always 128. Gamma controls the dot density:

Profile	Gamma	Dot density	When to use
Feinkorn-locker	0.7	~23% black	Bright images, loose grain
Feinkorn-mittel	1.0	~50% black	Natural gray-tone reproduction – starting point
Feinkorn-dicht	1.5	~77% black	Dark, dense grain
Feinkorn-max	2.5	~93% black	Maximum grain density

Profile recommendation for portraits

Goal	Profile
Like Inkscape	Inkscape-Korn
Finer than Inkscape	Ultra-Fein
Organic grain, natural gray tones	Feinkorn-mittel
Very dense grain	Feinkorn-dicht or Feinkorn-max
Stencil from a portrait	potrace Stencil

12. Fixing Staircase Edges on Diagonals

With a low Alphamax (e. g. 0.0–0.05, as in the "Ultra-Fein" profile), potrace draws diagonals as staircase steps – the typical pixel staircase pattern. Cause: Alphamax ≈ 0 produces pure polygons without curve smoothing.

Alphamax	Effect
0.00 – 0.05	Pure polygons → maximum grain, but staircases on diagonals
0.5	Compromise: grain remains, diagonals get smoothed
1.00	Smooth curves (Inkscape default) – no staircases
1.34	Maximum smoothing

Staircases in color mode (OpenCV color)

Inkscape produces smoother color areas because it internally runs potrace with alphamax=1.0 for every color layer. The recommended solution in BitmapTracer:

13. Profiles

Profiles store all settings. File: bt_profiles.json next to the EXE.

Action	Description
Load	Select a profile from the dropdown → click Load or just pick from the dropdown
Save	Store the current settings under a name
Export	Export as a .json file (share with others)
Import	Menu Profiles → Import
Delete	Menu Profiles → Delete profile

Bundled profiles

When loading a profile, a short description appears in the status bar. All profiles show a tooltip on hover. (Profile names are kept in German – they are identifiers shared between both languages.)

Profile	Engine	Description
Standard	OpenCV	Balanced settings for general images. OpenCV · mono · threshold 128.
5 Farben	OpenCV	5-color tracing with k-means. Good for logos and flat illustrations.
Stencil	OpenCV	Stencil-optimized: high contrast, hard edges. Ideal for stencils and cutting plotters.
potrace Foto	potrace	potrace engine with CLAHE preprocessing. Best quality for photos with even contrast.
potrace Stencil	potrace	potrace + high threshold for hard stencil edges. Bézier curves with maximum smoothing.
Bayer-Korn	potrace	Regular Bayer raster dithering. Even geometric dot pattern.
Halftone	potrace	Halftone print simulation: round dots like offset printing. Dot size adjustable via the halftone slider.
Zeitungsdruck	potrace	Coarse halftone raster for a newspaper-print look. High contrast, large dots.
Korn (OpenCV)	OpenCV	Floyd-Steinberg dithering with OpenCV. Organic, irregular dot grain.
Inkscape-Korn	potrace	potrace + Floyd-Steinberg: matches Inkscape's trace bitmap. Fine, natural grain.
Ultra-Fein	potrace	Minimal area, many contours. For delicate details in clean line drawings.
Farbe-potrace	potrace	k-means + potrace per color layer (like Inkscape scan). Every color = true Bézier curves. Slower, maximum quality.
Ultra-Korn	OpenCV	Extreme Floyd-Steinberg grain. High contrast + maximum dithering.
Bleistift	OpenCV	Simulates a pencil drawing: light lines on a light background. Canny edge detection + invert.
Logo hart	OpenCV	For logos and vector graphics: hard edges, no blur. High threshold, minimal smoothing.
Aquarell-Umriss	OpenCV	Soft contours like watercolor sketches. Bilateral filter + curve smoothing.
Siebdruck 3F	OpenCV	3-color screen-print simulation. k-means with 3 colors, hard edges.
Porträt Schatten	potrace	Portraits: emphasizes shadow areas. CLAHE + adapted threshold.
Kupferstich	potrace	Copperplate-engraving look: fine Bayer raster. Small raster size, high contrast.
Druckgrafik locker	potrace	Loose printmaking lines. Medium grain, relaxed contours.
Druckgrafik dicht	potrace	Dense printmaking: many tight lines. High grain, tight contour approximation.
Hochkontrast-Farbe	OpenCV	Color tracing with high contrast. Few colors, hard boundaries.
Invertiert	OpenCV	Inverted tracing: bright areas become the foreground. For dark images with bright subjects.

14. Export Formats

SVG

Universal vector format. Opens in Inkscape, Illustrator, CorelDRAW, web browsers. Native Bézier curves, color layers, hole detection (fill-rule nonzero – correct for browsers since v1.7).

PDF

Print-ready, scalable, with metadata and an author footer. Color layers are drawn as separate paths (no FILL_EVEN_ODD bug since v1.8.2).

DXF

CAD format. Y axis mirrored automatically. Bézier curves resolved into polylines. Color layers with truecolor. Compatible with AutoCAD R13+.

PNG

File → Export as PNG saves the tracing result as a raster image at original resolution. Ideal for web, laser-cutter raster engraving, or previews.

PNG for Inkscape

For Inkscape … exports the preprocessed image (after levels/CLAHE/dithering). Open it in Inkscape → Extensions → Trace Bitmap → Brightness cutoff. Combines BitmapTracer's preprocessing with Inkscape's tracing quality.

15. Undo & Redo

BitmapTracer keeps up to 20 settings steps in memory.

Action	Shortcut	Menu
Undo	Ctrl+Z	Edit → Undo
Redo	Ctrl+Y	Edit → Redo
Re-trace	F5	Toolbar → Re-trace
Cancel a running potrace trace (new in v1.9.18)	Esc	–

16. New features v1.9.5 – v1.10.6

v1.10.3 – Language switch stage 3: English manual

The language switch is complete: Handbuch_EN.html – a full English translation of the manual – is now part of the release. With the interface set to English, Help → Open manual (English) opens the English manual (with automatic fallback to the German one if the file is missing). In addition, the manual lookup now also searches the PyInstaller bundle (sys._MEIPASS) – previously the onefile EXE only found the manual if it happened to lie next to the EXE. bump_version.py gained a third invariant: a translation completeness check – every T("…") literal must have an entry in _TR_EN, otherwise the version bump aborts. This permanently prevents new UI texts from shipping untranslated.

v1.10.2 – Language switch stage 2: tooltips, profiles, status messages

The English interface now also covers all texts set at runtime: all ~48 tooltips (incl. the dynamic profile tooltip), all 23 profile descriptions (profile combobox tooltip and short status-bar text on loading a profile), all dynamic status messages (trace status, contour counters left and right, SVG preview, export, undo/redo and error messages, Esc cancel), the engine hint "potrace not found – Help > Set up potrace" and the complete batch export dialog (status, log, message boxes, folder dialog titles). Tooltips are translated when shown – a language switch takes effect there without a restart.

v1.10.0/v1.10.1 – Language switch German/English

Under View → Sprache / Language the interface language can be switched between German and English. The choice is stored in bt_config.json. The menu bar switches immediately; all other elements appear in the new language after a restart. If a translation is missing, the German text is shown automatically – an empty or broken text can never occur.

v1.9.21 – Invariant self-test & release standard

• FEATURE self-test in bump_version.py: before every version bump, project-wide code invariants are now checked automatically (AST-based, also detects multi-line calls). On violations the script aborts before changing anything. Checked: (1) all subprocess calls set creationflags (prevents the console flash in the EXE – this regression already occurred twice), (2) webbrowser.open() never uses manually built f-string addresses (prevents the umlaut/space bug from v1.9.19).
• Release standard bt_config.json: this file deliberately does not belong in the release ZIP. It only stores user state (window position, last export path, last profile) and would be overwritten on every update. The program creates it automatically on first start.

v1.9.20 – Code audit: three regressions fixed

• BUGFIX console flash (EXE): when automatically installing missing Python packages (pip), a black console window briefly opened per package in the EXE version. The call now runs invisibly in the background – like all other subprocesses.
• BUGFIX color tracing (potrace): in color mode with the potrace engine, crossing or overlapping contours of the same color could cut each other out (unwanted white holes appeared). The cause was the evenodd fill rule – now nonzero, identical to the SVG fix in v1.7 and the PDF fix in v1.9.17. True holes (e. g. the inside of an "O") remain correct because potrace outputs them with opposite path direction.
• BUGFIX SVG preview with umlauts in the path: the browser preview (Ctrl+P) built the file address manually and failed if the temporary path contained spaces or umlauts (e. g. Windows user name "Müller"). The address is now encoded correctly – consistent with all other browser calls.

v1.9.19 – BUGFIX: mini preview & PDF/DXF export with potrace

• CRITICAL BUGFIX (coordinates): with engine=potrace, the contours carried internally for PDF/DXF were stored in preview coordinates while the canvas dimensions were at original resolution. Visible consequences: (1) after recoloring or hiding a layer via the color palette bar, the tracing result shrank to a small fragment in the top left. (2) PDF and DXF exports with the potrace engine drew the subject tiny in the page corner. Both paths now use original coordinates throughout – like the OpenCV and color-potrace paths.
• PERF layer hiding: re-rendering on layer show/hide previously ran at full original resolution (several seconds per click on a 4000-px image). It now renders at preview dimensions – instant response, identical picture.
• Note: SVG export was never affected – it uses the true potrace paths, not the fallback contours.

v1.9.18 – Esc cancel & NumPy future-proofing

• FEATURE Esc cancel: a running potrace trace (mono and color mode) can now be cancelled with Esc. The potrace process is terminated immediately – previously you had to wait up to 60 seconds for the timeout. The status line shows Esc = cancel during potrace traces.
• FEATURE batch cancel tightened: the cancel button in batch export now also terminates the currently running potrace process, no longer just between two files.
• MAINTENANCE NumPy: _bayer_dither used NumPy's deprecated matrix class (np.bmat/.A). Migrated to np.block – identical result, future-proof.
• Note: pure OpenCV traces run in native cv2 routines and cannot be interrupted; Esc has no effect there.

v1.9.17 – Code review: 8 bugfixes

• FIX profile warning on exit: the comparison snapshot was accidentally reset to None on startup after restoring the last profile. Consequence: the "unsaved changes" warning never appeared after startup – only after manually loading a profile. Now initialized correctly.
• FIX profile tooltip stacking: every profile switch bound an additional tooltip to the profile combobox. After several switches, multiple stacked tooltip windows appeared. Now: one binding, the text is fetched dynamically when shown.
• FIX potrace preview with Auto (Otsu): the preview binarized with the UI threshold instead of the value actually determined by Otsu – preview and export diverged (also with dither filters). Now consistent.
• FIX zoom in input fields: typing + or - in text fields (fill color, direct entry, batch paths, profile name) simultaneously zoomed the preview. Now: zoom keys only act when no input field has focus.
• FIX batch export potrace SVG: SVGs from batch export (potrace, mono) were saved raw – without mm dimensions and copyright comment. Now identical to single export.
• FIX PDF background: hex background colors (#rrggbb) from profiles were rendered white in the PDF background (hole filling already handled hex). Now a unified color parser.
• FIX About dialog: the "NEW" lines were three versions out of date – now version-independent with a reference to the manual.
• MAINTENANCE: header docstring was at v1.9.13 (now maintained by bump_version.py) · BitmapTracer_Icon.png is bundled into the EXE (the icon fallback never worked in the EXE) · dead variable/import removed.

v1.9.16 – Performance & robustness

• FIX: auto-installer: input() replaced with sys.exit(1) – no longer hangs in headless environments.
• PERF: trace_potrace: image conversion optimized from RGB→BGR→gray to direct PIL .convert("L") – saves 2 conversion steps and RAM.
• FIX: tooltip display: try/except in _show() protects against GUI crashes from winfo_* errors on multi-monitor Linux.
• FIX: _coerce_settings() in load_profiles() and import_profile_json() – type casting against DEFAULT_SETTINGS prevents ValueError with manually edited JSON profiles.

v1.9.15 – Code cleanup & stability fixes

• FIX: DEFAULT_SETTINGS was missing "potrace_color_mode" – KeyError risk in the consistency check fixed.
• CLEANUP: _svg_path_to_points() – 220 lines of dead code removed (0 calls since v1.8.x).
• FIX: last_export_fmt removed from _collect() – prevented unnecessary re-traces after every export.
• FIX: batch export: _worker_safe() with exception protection – the "Go" button remained permanently disabled on unexpected errors.

v1.9.14 – Bugfixes & consistency

• FIX undo on profile load: _on_profile_load now calls _push_undo() before _apply() – accidentally loaded profiles can be reverted with Ctrl+Z.
• FIX version_info.txt: was 10 versions out of date (v1.9.3). Now correct; bitmap_tracer.spec actually embeds version_info.txt (was version_file=None).
• FIX bt_5_Farben.json: version number was still 1.9.12.
• FIX start_bitmap_tracer.bat: echo line still showed v1.9.12.
• FIX manual section 13: profile table completely replaced by PROFILE_DESCRIPTIONS (all 23 profiles with full text). Reference to the removed "Farbe-Glatt" profile corrected.
• FIX bump_version.py: extended to include bt_5_Farben.json and version_info.txt – both files are maintained on every version bump from now on.

v1.9.13 – Bugfixes & improvements

• Profile descriptions: all 23 profiles now have a tooltip on the selection box and show a short description in the status bar when loaded.
• FIX dirty flag: back-and-forth slider movements no longer trigger a false "unsaved" warning on exit.
• FIX last_profile: the most recently used profile is now fully loaded on startup (_apply()), not just set in the dropdown.
• FIX MRU: recently opened files now show a short directory path in the menu – same-named files from different folders are distinguishable.
• FIX potrace timeout: clear error message with a solution hint instead of a bare exception.
• FIX batch export: _is_tracing regression from v1.9.12 fixed (flag blocked live trace after opening the batch dialog).
• FIX _collect: last_export_fmt included in the profile snapshot.

v1.9.12 – Bugfixes & code quality

• CRITICAL BUGFIX: f-string syntax error on Python 3.10/11 fixed – webbrowser calls now use pathlib.Path.as_uri() instead of nested quotes.
• BUGFIX: thread guard in _run_trace – fast slider movements no longer start parallel potrace.exe instances; debounce retry after 300 ms.
• BUGFIX: trace_potrace_color: faulty color layers are now reported in the console instead of being silently ignored.
• CLEANUP: webbrowser no longer re-imported locally (2× redundancy removed).
• FIX SPEC: windnd added as hiddenimport → drag & drop now works reliably in the EXE.

v1.9.11 – Features & profile overhaul

• FEATURE: last export format restored on program start.
• FEATURE: PNG export: post-export dialog "Open now?" (consistent with SVG/PDF/DXF).
• FEATURE: manual can be opened directly from the Help menu.
• FEATURE: batch export: output folder can be opened after completion.
• FEATURE: export all profiles at once – every profile as its own JSON file (Profiles → Export all profiles …).
• PROFILES: 11 redundant profiles removed, 10 new ones with real visual differences (Bleistift, Logo hart, Aquarell-Umriss, Siebdruck 3F, Porträt Schatten, Kupferstich, Druckgrafik locker/dicht, Hochkontrast-Farbe, Invertiert).

Profile	Engine / mode	Visual result
Bleistift	OpenCV · Canny	Edges only, no fill – pencil drawing
Logo hart	OpenCV · mono	High threshold, sharp corners – logos/stamps
Aquarell-Umriss	OpenCV · Canny	Strong blur + soft lines – painterly
Siebdruck 3F	OpenCV · color	Only 3 colors, bold boundaries
Porträt Schatten	potrace · bilateral	Only shadows remain (brighter gamma)
Kupferstich	potrace · Bayer 4px	Geometric fine raster
Druckgrafik locker	potrace · no filter	Gamma 2.8 – loose Inkscape grain
Druckgrafik dicht	potrace · no filter	Gamma 1.4 – dense Inkscape grain
Hochkontrast-Farbe	OpenCV · color 8C	Bold color blocks
Invertiert	OpenCV · mono	White on black

v1.9.10 – Code review & fixes

• BUGFIX: export_pdf: background rect ignored hex colors (#rrggbb).
• BUGFIX: trace_potrace_color: fill-rule="evenodd" → "nonzero".
• BUGFIX: contour counter not reset after loading an image.
• BUGFIX: DEFAULT_SETTINGS was missing potrace_color_mode.
• BUGFIX: _init_vars: v_pot_color_mode hardcoded False.
• BUGFIX: hex copy message overwrote newer status messages.

v1.9.9 – PDF fix, post-export dialog, zoom shortcuts

• CRITICAL BUGFIX: PDF export in color mode: color layers were cut out.
• FEATURE: post-export dialog "Open file now?" (SVG/PDF/DXF).
• FEATURE: Ctrl++ / Ctrl+− / Ctrl+0 zoom shortcuts.

v1.9.8 – Full code review

• CRITICAL BUGFIX: fg3 missing in both themes → KeyError in the batch export dialog. Added.
• BUGFIX: color mode: invert=True had no effect. Fixed via bitwise_not per color mask.
• FEATURE: SVG temp files are cleaned up on exit.
• IMPROVEMENT: _zoom_step(factor) for +/− keyboard shortcuts.

v1.9.7 – SVG preview & contour count

• FEATURE: SVG preview in the browser (Ctrl+P / button / View menu).
• FEATURE: contour count permanently in the status bar left (file name | px | mm@DPI | N contours).

v1.9.6 – Invert bugfix

• CRITICAL BUGFIX: _thresh_flag(invert, for_potrace) – single source of truth for all threshold decisions.
• BUGFIX: Canny mode: invert flag had no effect → cv2.bitwise_not(edges).
• BUGFIX: potrace preview: inconsistent invert logic → unified.

v1.9.5 – Shortcuts & quality

• Ctrl+O = open image, Ctrl+S = save profile, F5 = re-trace, Ctrl+P = SVG preview, +/− = zoom
• "Save all profiles" in the Profiles menu
• Window geometry + last profile are saved on exit and restored on the next start
• Warning if unsaved profile changes exist on exit
• Drag & drop via windnd (optional, Windows-only)
• Status bar split: left permanent, right temporary messages
• No cmd window on potrace.exe calls (CREATE_NO_WINDOW)

17. How Invert Works

Since v1.9.6 there is a single function _thresh_flag(invert, for_potrace) that makes all threshold decisions:

Mode	invert=False	invert=True
OpenCV mono/color/canny	Black = foreground (BINARY_INV)	Bright = foreground (BINARY)
potrace (for binarization)	Black = foreground (BINARY)	Bright = foreground (BINARY_INV)
Canny	Edges normal	Edges inverted (bitwise_not)
Color mode	Masks normal	Masks inverted (bitwise_not per mask)

18. Tips & Tricks

Best results

• Portrait, fine grain: load the "Inkscape-Korn" or "Ultra-Fein" profile, fine-tune gamma with the mouse wheel
• Staircases on edges: raise Alphamax to 0.5–1.0 (Ultra-Fein uses 0.03 – very angular)
• Even finer than Inkscape: Alphamax 0.0, Opttolerance 3–4, min area 1
• Grain density: gamma below 1 = darken = more dots = denser grain
• Avoiding noise: Gaussian blur 1–2 before tracing
• Unknown source image: try Auto-Threshold (Otsu)
• Changing colors: in color mode, right-click the swatch after tracing
• Using a hex code: click the hex code in the swatch → instantly in the clipboard

Source image recommendations

Source	Profile	Blur
Portrait, Inkscape quality	Inkscape-Korn	0
Portrait, even finer	Ultra-Fein (raise Alphamax if needed)	0
Portrait, organic grain	Feinkorn-mittel	0
Logo / stamp (b/w)	Standard	1–2
Multicolor logo	5 Farben	1
Stencil from a photo	potrace Stencil	1
Photo → line drawing	potrace Foto, mode canny	1–2

19. System Requirements

Component	Minimum	Recommended
Operating system	Windows 10 64-bit	Windows 11 64-bit
RAM	512 MB free	2 GB free
Resolution	1280 × 720	1920 × 1080
Python (for the build)	3.10	3.13

Libraries used

Library	Purpose	License
OpenCV (cv2)	Image processing, contour detection	Apache 2.0
Pillow (PIL)	Image formats, preview	HPND
ReportLab	PDF export	BSD
NumPy	Array operations	BSD
tkinter	GUI	Python License
potrace	Vectorization engine (external)	GPL v2

20. Version History

The complete, detailed version history (German) is in Handbuch.html, section 20. Summary of the most important milestones:

Version	Key changes
v1.6 – v1.8.x	Thumbnail preview system · SVG fill-rule fix · MRU list · export path memory · synchronized zoom/pan · tooltips · color palette bar with hex copy · reset buttons.
v1.9.x	Invert unification (_thresh_flag) · SVG browser preview · PDF FILL_NON_ZERO fix · profile overhaul (23 profiles) · keyboard shortcuts · drag & drop · Esc cancel for potrace · potrace coordinate fix · invariant self-test in bump_version.py.
v1.10.0/1	Language switch German/English: menus, buttons, dialogs, main window (stage 1).
v1.10.5	Transparency bugfix (RGBA PNGs): Cut-out PNGs with transparent background are now handled correctly. Previously: convert('RGB') turned transparent pixels black → a black k-means cluster covered the entire background in the SVG export. Fix: the alpha channel is extracted and used as a mask – transparent pixels (alpha ≤ 127) are excluded from k-means (label = -1) and appear in no colour mask. Dilation is restricted to the opaque area. Result: transparent stays transparent in SVG export, regardless of subject colour. Also: potrace's own <rect fill="#000000"/> is now removed when bg_color=transparent.
v1.10.5	EXE improvements: bt_profiles.json, bt_5_Farben.json and potrace.exe are now embedded in the EXE (all 23 curated profiles and the potrace engine are available without separate files; a potrace.exe beside the EXE still takes priority). Icon path in the spec is now resolved via SPECPATH – icon was not found during build despite being present.
v1.10.6	EXE build fixes & improvements: Fixed SPECPATH error in spec (dirname(SPECPATH) returned wrong directory → potrace.exe and icons were not embedded). potrace radio button now refreshes after 500 ms automatically. potrace_available() with lazy reload. bt_profiles.json, bt_5_Farben.json and potrace.exe embedded in EXE; build_bitmap_tracer.bat downloads potrace automatically. find_potrace() also searches Python directory.
v1.10.5	Build fix: build_bitmap_tracer.bat now installs windnd – drag & drop was missing in the EXE without it.
v1.10.2	Language switch stage 2: all tooltips, profile descriptions, dynamic status messages, batch export dialog (+121 translations).
v1.10.3	Language switch stage 3: English manual (Handbuch_EN.html), language-aware Help menu entry, manual lookup also in the PyInstaller bundle, third bump invariant (translation completeness T()/_TR_EN).

21. Copyright & Disclaimer