Skip to content

Documentation

Jump to bottom Edit New page
Johannes Kalliauer edited this page Jan 22, 2022 · 7 revisions

//How can I create a table-of-conent in Markdown? (please help) :toc: :toc-title:

Options:

--version                      show program's version number and exit
-h, --help                     show this help message and exit
-q, --quiet                    suppress non-error output
-v, --verbose                  verbose output (statistics, etc.)
-i INPUT.SVG                   alternative way to specify input filename
-o OUTPUT.SVG                  alternative way to specify output filename

Bugs:

  • #158 Cyrillic characters in filename not suported

Optimization:

Optimization is about the processing/modifying/simplifying of the content of the file.

--set-precision=NUM

set number of significant digits (default: 5)

Enhancements: #139

It is possible to reduce the accuracy to reduce the file-size. Reducing the significant digits might lead to

  • misplaced objects
  • objects with a different shape
  • wrong shading/transparency
  • and other problems

In most cases 5 is more than enough, but if you see some inaccuracy you might want increase –set-precision=8, which can be seen as lossless.

If you want to reduce the file-size, or simplify the file, you can reduce –set-precision to 4,3,2,1 but always check if the output is still correct. If you see a difference it is not a scour-bug, it is a too strong lossy compression.

–set-precision=8 and –set-precision=1 (f.e. eyes of the cat are wrong)

(CC-BY-SA 3.0: Niabot, details)

Enhancements:

  • #139 Allow --set-precision 3.8 (now not supported)

--set-c-precision=NUM

set number of significant digits for control points (default: same as '--set-precision')

This option is similar to –set-precision, and therefore the value is per default the same as defined in --set-precision.

Reducing the significant digits might lead to

  • direction of lines wrong
  • and other problems

–set-c-precision=5 and –set-c-precision=1 (the green line of the road axis is not in the middle any more)
(CC-BY-SA 4.0: Johannes Kalliauer, details)

--disable-simplify-colors

won't convert colors to #RRGGBB format

Simplify colors converts the definition of the colors in the source code:
white->#fff
yellow->#ff0
fuchsia->#f0f
black->#000
this reduces the file size.
If you prefer keeping color-names you can use --disable-simplify-colors.

However aqua,gray,navy,silver,green,olive,teal,blue,lime,purple,maroon,red,cyan are always kept the same by scour since converting does not reduce file-size.

Example (if not disabled)

<svg xmlns="http://www.w3.org/2000/svg">
 <rect width="100%" height="100%" fill="#FF0000" stroke="fuchsia"/>
</svg>
<svg xmlns="http://www.w3.org/2000/svg">
 <rect width="100%" height="100%" fill="#f00" stroke="#f0f"/>
</svg>

Bugs:

  • #221 simplify-colors removes default value (overwrites CSS)

--disable-style-to-xml

won't convert styles into XML attributes

Per default scour converts style (f.e. style="fill:#ffff00;fill-rule:evenodd;stroke:#ffffff;stroke-width:0.5") to xml-attributes (f.e. fill="#ff0" fill-rule="evenodd" stroke="#fff" stroke-width=".5") this can increase or decrease file-size. This can be disabled using --disable-style-to-xml.

Example

<svg xmlns="http://www.w3.org/2000/svg">
 <rect x="14" y="23" width="200" height="50" style="fill:#ffff00;fill-rule:evenodd;stroke:#ffffff;stroke-width:0.5"/>
</svg>
<svg xmlns="http://www.w3.org/2000/svg">
 <rect x="14" y="23" width="200" height="50" fill="#ff0" fill-rule="evenodd" stroke="#fff" stroke-width=".5"/>
</svg>

Bugs:

  • #176 (->CSS: #174) If <style type="text/css"> is available, this can lead to change of the rendering if conflicting attribute-values are defined in style= an in ´<style`.
  • #221 removes default value (overwrites CSS)

--disable-group-collapsing

won't collapse <g> elements

Group-collapsing will reduce file-size. Disabling group-collapsing keeps existing groups as they are. This option should be used if you want that grouped objects, are kept grouped. (f.e. That you can move them together)

Example (if not disabled)

<svg xmlns="http://www.w3.org/2000/svg">
 <text font-size="12pt" font-family="Liberation Sans,Arial,Nimbus Sans L,Helvetica,sans-serif" y="10">erste Zeile</text>
 <text font-size="12pt" font-family="Liberation Sans,Arial,Nimbus Sans L,Helvetica,sans-serif" y="20">2nd line</text>
</svg>
<svg xmlns="http://www.w3.org/2000/svg">
 <g font-size="12pt" font-family="Liberation Sans,Arial,Nimbus Sans L,Helvetica,sans-serif">
  <text y="10">erste Zeile</text>
  <text y="20">zweite Zeile</text>
 </g>
</svg>

Enhancements:

  • #124 collapse multiple <g> elements
  • #130 remove transforms on group
  • #215 apply attributes to single tag in the group
  • #216 goups are collapsed also option --disable-group-collapsing is used

--create-groups

create <g> elements for runs of elements with identical attributes

Create-groups will reduce file-size in most cases. Example if a file has hundreds of green <lines it does not make sense to define every line with stroke=”green”, therefore scour creates a <group that everything within that group is rendered stroke=”green” and therefore has only to be defined once, this has also the advantage that changing the color of those lines can easily be done just by changing one value and it reduces the file-size.

Example: (if enabled)

<svg xmlns="http://www.w3.org/2000/svg">
 <text font-size="12pt" font-family="Liberation Sans,Arial,Nimbus Sans L,Helvetica,sans-serif" y="10">erste Zeile</text>
 <text font-size="12pt" font-family="Liberation Sans,Arial,Nimbus Sans L,Helvetica,sans-serif" y="20">zweite Zeile</text>
</svg>
<svg xmlns="http://www.w3.org/2000/svg">
 <g font-size="12pt" font-family="Liberation Sans,Arial,Nimbus Sans L,Helvetica,sans-serif">
  <text y="10">erste Zeile</text>
  <text y="20">zweite Zeile</text>
 </g>
</svg>

Problems and Enhancements:

  • #196 wrong rendering by Chrome when --create-groups is chosen.
  • #204 no grouping occours
  • #258 style not grouped
  • #286 breaks file with stroke-linejoin

--keep-editor-data

won't remove Inkscape, Sodipodi, Adobe Illustrator or Sketch elements and attributes

Currently no Bugs know.

--keep-editor-data are generally elements which are not rendered, they are used for editing (f.e help for aligning elements in editor), such as: <sodipodi:guides or <inkscape:grids or inkscape:groupmode="layer" inkscape:label="Layer 1". If you want to publish a picture you should remove those data and it reduces the file-size and makes the file SVG-DTD-valid, but if you prefer to edit the file further you should keep the editor data, also it won’t be a W3C-SVG-DTD-valid SVG-file.

--keep-unreferenced-defs

won't remove elements within the defs container that are unreferenced

Known Bugs with --keep-unreferenced-defs: #203 Known Bugs without --keep-unreferenced-defs: #155 (->CSS: #174)

Unreferenced Definitions are useless and should be cleaned up. A Definition, can for example be a color gradient of a rectangle going from black to white. It might occur that after deleting the rectangle the color gradient is still defined, but not used anymore and therefore useless and should be removed. (This function is similar to vacuuming in Inkscape

For Source-Code-Editors, who edit the file by hand with texteditors (without editors, such as Inkscape) might

  • temporarily remove some parts to edit them somewhere else and want to keep the definitions also the file is processed with scour
  • or want change between definitions applied to one object (f.e. Same Picture with different backgrounds) then they should use the option --keep-unreferenced-defs

Bugs:

  • #155 (->CSS: #174) If <style type="text/css"> is available, scour might sees that a definition is not used in the regular SVG-Code, but it might occur that it is used in <style type="text/css"
  • #203 (Pull: #207) In combination with --enable-id-stripping: leads to a wrong referencing on ids.

--renderer-workaround and --no-renderer-workaround

--renderer-workaround work around various renderer bugs (currently only librsvg) (default)
--no-renderer-workaround do not work around various renderer bugs (currently only librsvg)

Currently no Bugs known. But defining --no-renderer-workaround might lead that that a correct SVG-file is displayed wrong.

Librsvg is one common Renderer-library (used by most Linux-SVG-Viewers or by Wikimedia (f.e. Wikipedia), which renders SVG-files sometimes wrongly. Some bugs are well known by the developers, but since it is free of charge it sometimes takes a long time to correct them, therefore scour offers workarounds to overcome this problem.

If your svgs are only rendered by Inkscape, Google Chrome, Firefox or other software that processes common SVG correctly, you can use --no-renderer-workaround which reduces the file-size.

Left --render-workaround, right --no-renderer-workaround (both are rendered by Wikimedia) (Public Domain: details&source(left) details&source(right))

(Public Domain: details, source)

Problems:

  • wrong rendering by librsvg if --no-renderer-workaround is chosen.

SVG document:

This topic does not change the content that is rendered it is about the options how the file is displayed/formatted.

--strip-xml-prolog

won't output the XML prolog (<?xml ?>)

Currently no Bugs know. But enabling --strip-xml-prolog might lead to not rendering the file.

A XML prolog is a processing instruction (Wikipedia) defines the Syntax-version of the Extensible Markup Language (Wikipedia) and the encoding. --strip-xml-prolog removes the <?xml version="1.0" encoding="UTF-8"?> at the beginning, which is not recommended also it reduces the file size

Problems:

  • Some renderer/browser might not display the file if does not include <?xml version="1.0" encoding="UTF-8".

--remove-titles and --remove-descriptions

--remove-titles remove <title> elements
--remove-descriptions remove <desc> elements

No Bugs known.

Some viewer display the title instead of the filename if a SVG-Title is available. Titles are added on purpose by the editor of the file to name the SVG-file or to label specific elements (f.e. title of the <path is the name of the region/country). Descriptions are added on purpose by the editor and contain information about the file or some tags/elements, sometimes also Autor and License is saved there. If the file is just for viewing and not for further editing you can --remove-titles and/or --remove-descriptions to reduce file-size.

--remove-metadata

remove <metadata> elements (which may contain license/author information etc.)

No Bugs known. Enhancements: #222

Removing metadata might be a copyright infringement, since metadata should contain information about the authors the license, the rights, the permission, the source, the creation date,… . Inkscape always saves metadata, even if it is empty. In such cases it is save to --remove-metadata. --remove-metadata is necessary to get a W3C-SVG-DTD-valid SVG-file.

Enhancements:

  • #222 only remove metadata if empty, otherwise it might be a copyright violation

--remove-descriptive-elements

remove <title>, <desc> and <metadata> elements

No Bugs know.

For reducing file-size you can ´ --remove-descriptive-elementswhich is identical with --remove-titles --remove-descriptions --remove-metadata`. Explanation of the three individual options can be read above.

--enable-comment-stripping

remove all comments (<!-- -->)

No Bugs known.

SVG files can contain text comments that are only visible when looking at the file in a text editor. They are irrelevant for rendering of a file but can have informational value --enable-comment-stripping will remove all comments from the file, therefore reducing the file size Comments are used for several reasons:

  • declare the software the file was created (f.e. <!-- Generator: Adobe Illustrator 13.0.0, SVG Export Plug-In . SVG Version: 6.00 Build 14948) -->)
  • explain how the file is structured, what is coming next/before in the source-code
  • it can be used to hide elements (f.e. background-image), which can be easily be unhided (as long as it is not removed)
  • as a description/title (alternative to <title>/<desc>, see above)
  • declare author/license (should be in metadata)

If you don’t need the comments and want to reduce the file-size you can --enable-comment-stripping.

--disable-embed-rasters

won't embed rasters as base64-encoded data No Bugs known. But --disable-embed-raster might lead that external files are not included.

SVG-Files including external images (f.e. <image xlink:href="https://upload.wikimedia.org/wikipedia/commons/8/86/SaoPaulo_MesoMicroMunicip.svg"/>example or <image xlink:href="file:///C:/Documents%20and%20Settings/ASSATIANI/Mes%20documents/Caucasus_topo_map-blank.jpg" />example) will be by default embedded. Per default the external file will be included in the SVG-file (if it can be found [in the internet]/[locally]), which increases the file-size, but displaying the external image will then also work if the source is not available any more. Some software such as Wikimedia blocks external images due to security reasons, therefore embedding SVG/PNG/JPEG will be less problematic.

If you plan to edit the PNG/JPEG externally (f.e. with Gimp) and you always want that the SVG takes the actual PNG/JPEG -file then you should --disable-embed-rasters. Scour cannot embed SVGs (possible, but not implemented, since it is very uncommon), this can be done other software such as Inkscape.

--enable-viewboxing

changes document width/height to 100%/100% and creates viewbox coordinates

No Bugs known.

--enable-viewboxing will change the size of the preview (in common browsers& by Wikimedia, but f.e. not by Inkscape) if no viewBox= is available, if a viewBox=is available, this option does not change anything, and the preview will be the same. Browsers show svgfiles with viewBox= (but without “width=” and without “height=”) in such a way that the file fits into the window and is shown as big as possible. Browsers center svgfiles with viewBox= and also view everything outside the viewBox= if there would be white space.

There are four possible options:

  1. neither viewBox= nor width=”…” height=”…” is used (the image is shown in original resolution) [Comment: valid option, but rarely used, since the picture-dimension can be problematic]: this option does not change anything
  2. width=”…” height=”…” is used, but no viewBox= is defined (the image is shown in the specified width and height in original resolution): --enable-viewboxing will change it to option 3
  3. viewBox= is defined, but no width=”…” height=”…” is available (the image is shown in tight fit): this option does not change anything
  4. viewBox= and width=”…” height=”…” are defined (Only the part in viewBox is shown, and it is scaled down (centered and kept aspect ratio) to fit into width=”…” and height=”…”): this option does not change anything

Output formatting:

This does define how the svg is formatted in the source-code. Output formation does not change any content, it is just how the code is presented/saved. If you just use SVG-editors such as Inkscape you will only notice the difference in the size of the file.

--indent=TYPE and --nindent=NUM and --no-line-breaks

--indent=TYPE indentation of the output: none, space, tab (default: space) --nindent=NUM depth of the indentation, i.e. number of spaces/tabs: (default: 1) --no-line-breaks do not create line breaks in output(also disables indentation; might be overridden by xml:space="preserve")

No Bugs known.

For source-code-editors indentation is a very helpful tool to have a human-readable SVG-structure. If you only edit with SVG-Editors you won’t notice a difference.

If you want to minimize the file-size you should use --no-line-breaks. (Files without linebreak don’t need any indentation, therefore the other two options are irrelevant).

If you are a source-code-editor and you are reading the files with a texteditor, linebreaks will make your live much easier, if not just say with the default values. If you choose --indent=none or --nindent=0 or both will lead to no indentation. If you like indents and how many is upon you.

If a file contains xml:space="preserve" scour will not change the white spaces since it is unwanted, see next point how to bypass this problem.

--strip-xml-space

strip the xml:space="preserve" attribute from the root SVG element

Known Bugs: #212

The attribute xml:space="preserve" means that the white spaces (spaces, tabs, line breaks) should be kept in place and with the same amount. Therefore, this option overwrites the indentformat described above. If you would like to ignore xml:space="preserve" in the root-<svg-tag you should add the option --strip-xml-space. Child-<svg-tags example won’t get changed with this option. The meaning of xml:space-Attribute is explained by Mozilla

Bugs:

  • #212 If xml:space="preserve" is in the root-<svg-tag and is essential in a <text-tag, without redefinition, the text will be rendered with less spaces.


(License:cc-by-sa-3.0; Author: Ra'ike; source)

--enable-id-stripping and --shorten-ids

--enable-id-stripping remove all unreferenced IDs
--shorten-ids shorten all IDs to the least number of letters possible

Bugs with --enable-id-stripping: #164 (->CSS #174); #203 (Pull: #207) Bugs with --shorten-ids: #164 (->CSS #174) Issues with --shorten-ids: #186

ID attributes: id=”…”-names are unique identifier to access a certain element and can be essential in svgs.

Even if they are not essential, id=”…”-names can be very helpful for labeling, in maps for example they can be used for labeling <path with the name of the according region/country, and should neither be removed nor shortened.

There are two kinds of ids, some of them are essential for rendering, others are just labels. If an id is not essential it will be removed with the option --enable-id-stripping. (Later it is explained how you can define exceptions.) If an id is kept, it can be shortened with --shorten-ids, which will reduce file size in most cases.

Bugs and Issues:

  • #164 If <style type="text/css"> is available, it can occur that --enable-id-stripping or --shorten-ids (or both) lead to breaking the file.
  • #186 If a svg-file already contains (many) shorten-ids it can happen that --shorten-ids increases the file-size. (Then do not activate --shorten-ids.)
  • #203 (Pull: #207) In combination with --keep-unreferenced-defs: leads to a wrong referencing on ids.

--shorten-ids-prefix=PREFIX

add custom prefix to shortened IDs

No Bugs known.

This option only works with --shorten-ids. If you want that all changed id starts with “blablaBlub” then choose the option --shorten-ids-prefix=blablaBlub, this will increase the file-size. Remember valid id-names must not contain any spaces or commas, and the first sign must not be a digit. This option is only helpful for specific tasks, if you don’t understand it, you won’t need it. It can be helpful if you want to merge two files manually (with a text-editor) together: Since id have to be unique, Copy-Pasting will lead to errors, therefore you define two different prefix for both files and so it can be achieve unique ids. If you want to minimize the file-size, this can be used as a workaround for issue #186. (first time running with --shorten-ids-prefix, second time without)

--protect-ids-noninkscape

don't remove IDs not ending with a digit

No Bugs known.

This option adds exceptions to the options --shorten-ids and --enable-id-stripping. Inkscape labels all tags with ids (f.e. id="path6843") and all of them end with a digit. Most labels by humans end with a letter (f.e. id="Nigeria:Taraba_State", id="Ajdovščina", id="Bristol_Bay__AK"example) Labels created by --shorten-ids only contain letters. Since id="path6843" is in most cases without meaning, it makes sense to remove/shorten such ids (ending with a digit), but keep all other(not ending wit a digit), therfore you can specify --enable-id-stripping --shorten-ids --protect-ids-noninkscape. Caution: Some id-names, not created by inkscape, also end with a digit, for example a postal code, this id-names will not be protected by this flag, and therefore might get removed, which might be unwanted.

--protect-ids-list=LIST

don't remove IDs given in this comma-separated list

No Bugs known.

You can protect specific ids, to not be shortened/removed. This can be helpful f.e. if it contains specific definitions which are not needed in the actual file, but for later changes this definitions should be available. f.e. if you use --protect-ids-list=blur1,blur2,blur3,blur4, then blur1, blur2, blur3 and blur4 will be kept also they may not be used. This option is only helpful for specific tasks, if you don’t understand it, you won’t need it.

--protect-ids-prefix=PREFIX

don't remove IDs starting with the given prefix

No Bugs known.

You can protect ids with a specific prefix. f.e. You are interested in a specific element you name it id=LetsTrySomething1 the next you call id=LetsTrySomething2, then you can keep those id-names by specifying --protect-ids-prefix=LetsTrySomething (This will also protect id=LetsTrySomethingElse1.). This option is only helpful for specific tasks, if you don’t understand it, you won’t need it.

SVG compatibility checks:

This topic is about checks if the file is SVG-1.1-valid.

--error-on-flowtext

exit with error if the input SVG uses non-standard flowing text (only warn by default)

Enhancements: #203

Inkscape uses <flowRoot-tags which will get a SVG-feature in future, it is suggested by the unpublished SVG version 1.2. The last published version of SVG is 1.1. The last working draft of SVG 1.2 is more than 10 years ago (April 2005). Flowtext is hardly supported: browsers won’t render it and librsvg (as used in Wikimedia and on most linux-Computers) mostly show black rectangles.

Scour by default warns the user that flowtext is available, because black rectangles often disturb the picture. If want that scour stops working if the file contains flowtext, you can enable --error-on-flowtext. (Especially helpful if you do bulk-processing (many SVGs in one folder), otherwise you might miss warnings unintentionally.)

If a flowtext contains text it is the best thing to convert it with Inkscapeexplantation. If a flowtext does not contain text it cannot be removed by Inkscape, see RepairFlowRoot for other options.

(CC-BY-SA 3.0: User:Gustavb source)

Enhancements:

  • #203 remove empty flowtext

CSS

Bugs: #174

CSS-Support is not supported, but in most cases scour will process also SVG files containing CSS right.

If you scour a svg-file with CSS you should add following options for workaround on the save side:

--keep-unreferenced-defs --disable-style-to-xml --disable-simplify-colors

  • --keep-unreferenced-defs #155
  • --disable-style-to-xml #176
  • --disable-simplify-colors #221

Do not use following options:

  • --enable-id-stripping #164
  • --shorten-ids #164

Bugs:

  • #174 Add support for global CSS and add proper CSS parsing

Bugreporting

If scour breaks a file you might should start with a save-mode-run:

scour -i input.svg -o output.svg --disable-simplify-colors --disable-style-to-xml  --disable-group-collapsing --keep-editor-data --keep-unreferenced-defs --protect-ids-noninkscape  --disable-embed-rasters --set-precision=8 --set-c-precision=8

Bugs occouring in the save-mode:

  • #211 a part of the path gets a black fill
  • #157 CSS-Problem: removement of default value
  • #276 removes fill in text
  • #281 text-anchor="start" removed in defs

If you see another bug can report a new issue

If a bug does not occour in the save mode you might should try the default options:

scour input.svg output.svg

this is identical to:

scour -i input.svg -o output2.svg --set-precision=5 --set-c-precision=5 --renderer-workaround --indent=space --nindent=1

If the bug is occouring in the default mode, check which of the options is reponsible for the bug and check the bugreports in the according sectors. If the bug is still not occouring you can try to add further options to get the bug and check the bugreports in the according sector.

The maximal version of Optimizing is:

scour -i input.svg -o output.svg --enable-comment-stripping --strip-xml-space --remove-metadata --renderer-workaround --remove-descriptions --enable-id-stripping --shorten-ids --set-precision=5 --set-c-precision=5 --create-groups --remove-descriptive-elements --remove-titles  --enable-viewboxing

If you just want to minimize the file-size you might try:

scour -i input.svg -o output.svg --enable-comment-stripping --remove-titles --remove-descriptions --disable-embed-rasters --strip-xml-space  --create-groups --remove-metadata --remove-descriptive-elements --enable-id-stripping --shorten-ids --set-precision=3 --set-c-precision=2 --error-on-flowtext --no-line-breaks --indent=none --no-renderer-workaround

but this can lead to inaccurat rendering or even bugs.

Suggesting Enhancements:

You can suggest enhancements, with creating a new issue. But please consider that everyone is woking voluntary for this project and therefore implementing can take time or might get refused.
Otherwhise you can also try other SVG-tools such as svgo or svgcleaner.

Add a custom footer
Add a custom sidebar
Clone this wiki locally