Image converter configuration wsimageconvert.cfg

The image converter takes images from a source directory, converts them into one or more target formats, and stores the results in the shop’s directories. What happens in the process is defined in the wsimageconvert.cfg file in the auto-konvertierung directory. The file has two sections. Basic controls what applies to the entire run, that is, transfer lists and the handling of subdirectories. Convert contains one +Entry subsection per target format, with source, target, file type, and the arguments for the conversion program. To edit the file, download it, change it, and upload it back to the server. Guide: Image converter

File structure

<Basic>
   TransferList-Allow             =
   TransferListDirectory          =
   TransferListSrcDirectory       =
   TransferListRemoveSrcDirectory =
   KeepSubDirectories             =
   DeleteSrcSubDirectories        =
</Basic>

<Convert>
   <+Entry>
      Name             =
      Type             =
      DestDir          =
      SrcDir           =
      ExclDir          =
      ConvertArgs      =
      ConvertArgs-JPG  =
      ConvertArgs-PNG  =
      ConvertArgs-GIF  =
      ConvertArgs-Webp =
   </+Entry>
   ...
</Convert>

`Basic`

Transfer lists

A transfer list is a text file containing all files that a run has converted. It serves as a handover to downstream systems that need to know which images are new.

Parameter	Purpose	Values
`TransferList-Allow`	create transfer lists	`yes`, `no`. Default: `no`
`TransferListDirectory`	directory in which the lists are stored	path relative to the shop directory
`TransferListSrcDirectory`	write only images from this subdirectory to the list	subdirectory
`TransferListRemoveSrcDirectory`	remove this subdirectory from the entries	`yes`, `no`. Default: `no`

TransferListDirectory is required as soon as TransferList-Allow is set to yes. You must create the directory manually on the server beforehand; the converter doesn’t create it. TransferListSrcDirectory is optional. Without this parameter, all converted images end up in the list. With it, only those from the specified subdirectory do; all others are left out. TransferListRemoveSrcDirectory can only be used together with TransferListSrcDirectory and strips its name from the entries. The file name of a transfer list consists of the date and a sequential number that restarts each day.

20260930-0.dat

The content is a list of paths, one file per line.

produkte/klein/04202C2.PNG
produkte/klein/360030C.PNG

Subdirectories

You can create subdirectories in the source directory auto-konvertierung/quellbilder, for example auto-konvertierung/quellbilder/produkte. The converter searches the source directory including all its subdirectories for files.

Parameter	Purpose	Values
`KeepSubDirectories`	carry the directory structure over to the target directories	`yes`, `no`. Default: `no`
`DeleteSrcSubDirectories`	delete empty subdirectories after the run	`yes`, `no`. Default: `no`

By default, all converted files are placed flat, directly in the target directory. The structure from the source directory is lost in the process. KeepSubDirectories = yes replicates it in the target directory and creates missing directories automatically. DeleteSrcSubDirectories = yes cleans up the subdirectories in the source directory after the run. A directory is deleted only if it no longer contains any images.

`Convert`

One +Entry subsection per target format. A source image passes through all entries that match it and thus produces multiple outputs in different sizes and formats.

<Convert>
   <+Entry>
      Name        = jpg-Produktbild 1000x1000 Pixel
      DestDir     = websale8_shop-xyz/produkte/medien/bilder/gross
      SrcDir      = produkte/gross
      ConvertArgs = -resize 1000x1000> -background white -compose Copy -gravity center -extent 1000x1000 -quality 80 -strip
   </+Entry>
</Convert>

Required parameters

Parameter	Purpose	Values
`Name`	description of the format	text, for example `jpg-Produktbild 1000x1000 Pixel`
`DestDir`	target directory of the converted files	path relative to the shop’s root directory
`ConvertArgs`	command-line arguments for ImageMagick	see below

Name appears in the online service area in the Image converter service on the start page under the heading “Konvertierungs-Formate”. Choose the text so that you can recognize the format there.

These three parameters are required. If any of them is missing, the entire +Entry is silently skipped. No error message appears; the format is simply missing from the result.ConvertArgs must be present but can be left empty. This is necessary, among other things, when converting to webp.The fact that all three parameters are required isn’t described in the previous documentation and has been added here.

The converter normalizes the path in DestDir so that it can’t lead outside the shop directory. Paths with .. therefore have no effect.

Restricting the source

Parameter	Purpose	Values
`SrcDir`	consider only these subdirectories	directories, multiple separated by a vertical bar
`ExclDir`	exclude these subdirectories	directories, multiple separated by a vertical bar

Both settings refer to subdirectories of auto-konvertierung/quellbilder.

SrcDir  = produkte/gross|produkte/klein
ExclDir = produkte/intern

Without SrcDir, all directories including the main directory are considered. With SrcDir, only the listed ones are; all others are ignored. You usually need ExclDir only when no SrcDir is set.

ExclDir compares the beginning of the path, not an arbitrary part of it. ExclDir = produkte therefore excludes produkte/gross, but not archiv/produkte. Spaces around the directory names are removed. Neither of these is documented; both have been added here.

File type

Parameter	Purpose	Values
`Type`	file type to convert to	`jpg`, `png`, `gif`, `webp`, and other spellings

If Type is left empty, the file keeps its type. The following table shows which conversions are possible.

From	To jpg, png, gif	To webp
`.jpg`	yes	yes
`.png`	yes	yes
`.gif`	yes	no
`.webp`	no	no

The spelling of Type determines the spelling of the file extension. With Type = png, 04531.PNG becomes 04531.png, whereas with Type = Png it becomes 04531.Png.An unsupported conversion doesn’t produce an error message in the shop. The file is just skipped and the reason is written to the log.

Conversion arguments

ConvertArgs contains the command-line arguments that are passed to ImageMagick. This is where you define what happens to the file, such as cropping, padding, scaling, or compressing.

ConvertArgs = -resize 400x400> -background white -compose Copy -gravity center -extent 400x400 -quality 80 -strip

You can override this value for individual source formats.

Parameter	Overrides `ConvertArgs` for
`ConvertArgs-JPG`	files with the extension `.jpg` or `.jpeg`
`ConvertArgs-PNG`	files with the extension `.png`
`ConvertArgs-GIF`	files with the extension `.gif`
`ConvertArgs-Webp`	arguments for `cwebp`, see below

The extensions are recognized regardless of upper and lower case.

The converter splits the arguments at spaces. An argument value that itself contains a space therefore can’t be passed. This isn’t documented and has been added here.

The -sharpen option costs a disproportionate amount of runtime. Even -sharpen 0 doubles the conversion time without sharpening at all. With -sharpen 5, the difference is fivefold. In addition, the file size of the result increases.Sharpening plays a minor role in the final quality of the images. When in doubt, leave it out.

Converting to webp

For webp, the converter works in two stages, because ImageMagick doesn’t generate this format on the platform in use.

ImageMagick applies the changes from ConvertArgs and writes a temporary file.
The cwebp program converts this temporary file to webp using the arguments from ConvertArgs-Webp.

<+Entry>
   Name             = webp-Produktbild 400x400 Pixel
   Type             = webp
   DestDir          = websale8_shop-xyz/produkte/medien/bilder/webp
   ConvertArgs      = -colorspace rgb
   ConvertArgs-Webp = -resize 400 400 -q 80
</+Entry>

Three conditions must be met for the conversion to webp to work.Type must be set to webp. Without this value, ConvertArgs-Webp isn’t evaluated at all.ConvertArgs must be present, even if it contains no value.cwebp doesn’t support the CMYK color space. Therefore, specify the -colorspace rgb parameter in ConvertArgs; otherwise, the conversion fails for images from prepress.

You can find a list of the possible arguments for cwebp in Google’s documentation at developers.google.com/speed/webp/docs/cwebp.

What happens to faulty source files

The converter checks each source file twice: first the file extension, then the first bytes of the file to determine whether the content really matches the specified format.

If a file fails either of these checks, it’s deleted from the source directory and an entry is created in the error log. The file is gone afterward.This affects files with an unsupported extension as well as files whose content doesn’t match the extension, for example a PDF file renamed to .jpg.This behavior isn’t described in the previous documentation and has been added here. Therefore, never store source images exclusively in the conversion directory.

When something doesn’t work

Observation	Possible cause
A format is completely missing from the result	`Name`, `DestDir`, or `ConvertArgs` is missing in the `+Entry`. The entry is then skipped entirely
The transfer list isn’t written	`TransferListDirectory` is missing, or the directory doesn’t exist on the server
The transfer list is empty	`TransferListSrcDirectory` points to a subdirectory in which nothing was converted
All images are placed flat in the target directory	`KeepSubDirectories` is set to `no`
Individual source files have disappeared without a trace	They failed one of the two format checks and were deleted. The reason is in the error log
webp files aren’t created	`Type` isn’t set to `webp`, `ConvertArgs` is missing entirely, or the source is a `.gif` or `.webp` file
webp fails only for individual images	These images are in the CMYK color space. `-colorspace rgb` is missing in `ConvertArgs`
The conversion takes noticeably long	`ConvertArgs` contains `-sharpen`
The file extension has an unusual spelling	The spelling comes from `Type`

You can find the error messages of a run in the online service area in the Image converter service.

​File structure

​Basic

​Transfer lists

​Subdirectories

​Convert

​Required parameters

​Restricting the source

​File type

​Conversion arguments

​Converting to webp

​What happens to faulty source files

​When something doesn’t work

File structure

`Basic`

Transfer lists

Subdirectories

`Convert`

Required parameters

Restricting the source

File type

Conversion arguments

Converting to webp

What happens to faulty source files

When something doesn’t work