Umriss

Traces black-and-white bitmaps into SVG.

⚠️ The project is currently under development.

While Umriss can be used for tracing graphics, its main orientation is scanned documents and books. It generates compact SVG files which, after compressing into SVGZ, are comparable in size to the traditional bitmap formats or even smaller. Some planned features, such as glyph reusing (TODO), can reduce the size even further.

Umriss uses several tracing methods, both lossless and lossy.

Usage

(TODO)

A CLI is not yet implemented. Edit the __main__.py file to change settings.

Before tracing, the input bitmap is binarized using the simplest threshold method. For better quality, consider binarizing the image beforehand using a more advanced binarization method. For scans, ScanTailor or ScanTailor Advanced would be great choices.

The code is not optimized yet. Execution can take quite a few seconds on a single image.

Tracing methods

Exact

Creates an exact contour around the black pixels of the image.

The file sizes can even be smaller than those of lossily approximating methods due to using h and v SVG node types with integer relative coordinates.

AccuratePolygon

Approximates a pixel contour with a polygon.

The resulting contour, when rasterized again into a black-and-white bitmap, should match the original bitmap. So, this tracing method can be considered lossless.

Maximum Hausdorff distance between the original and the result contours is 0.5 px.

Preserves the symmetries of the original image.

Parameters:

• max_slope_ratio (positive integer, default value: 10)

  Defines maximum slope ratio. E.g. if the value is 10, then 10 px by 1 px stepped line will be considered a slope while 11 or more by 1 will contain horizontal/vertical segments. Higher values give smoother contours, but if the value is too high, there won't be any horizontal or vertical line in the image.

  original	max_slope_ratio = 2
  max_slope_ratio = 10	max_slope_ratio = 18

• corner_offset (range: 0.0..0.25, default value: 0.25)

  Makes the contours smoother by offsetting sharp corners. On the other hand, makes some small details look worse. Values greater than 0.25 are not supported because of possible losslessness violation.

  corner_offset = 0	corner_offset = 0.25

DouglasPeuckerPolygon

Approximates contours with polygons using the Douglas—Peucker algorithm from OpenCV.

The maximum Hausdorff distance between the original and the result can be specified.

The algorithm does not create any new points. It only drops some points of the input contour.

Parameters:

• max_distance (positive, default value: 1.0)

• preliminary_approximation (optional, default value: None)

  A polygonal approximation that is used before the Douglas—Peucker approximation.

preliminary approximation	max_distance = 0.5	max_distance = 1	max_distance = 2
None
AccuratePolygon

Quadratic

(TODO)

Approximates the contours with quadratic Bézier splines so that the distance between the spline and the original contour never exceeds the given maximum value. Tries to minimize node count.

SillyCubic

(For test purposes only. Results can be pretty terrible.)

Applies a given polygonal approximation first. Then, draws a smooth cubic spline between the even points of the polygon. The odd ones are used for tangents in a not-so-clever way.

Parameters:

• polygonal_approximation

  An approximation used before the cubic approximation.

  polygonal_approximation = AccuratePolygon	polygonal_approximation = DouglasPeuckerPolygon(1)

File size comparison

Here are some examples of traced sccanned pages and their sizes.

File type	Page 1	Page 2	Page 3
png (1 bit per pixel)	339 kB	365 kB	567 kB
tiff (CCITT Group 4)	160 kB	156 kB	206 kB
svg/svgz Exact	1088 / 171 kB	1162 / 180 kB	1377 / 197 kB
svg/svgz AccuratePolygon	1289 / 243 kB	1370 / 258 kB	1302 / 259 kB
svg/svgz DouglasPeucker(1)	551 / 173 kB	603 / 188 kB	445 / 156 kB