> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Image converter configuration wsimageconvert.cfg

> The two sections of the wsimageconvert.cfg configuration: basic settings for transfer lists and subdirectories, and the individual conversion formats with source directory, target directory, file type, and ImageMagick arguments.

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

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<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.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
20260930-0.dat
```

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

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
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.

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<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.

> [!WARNING]
>
> 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.

> [!NOTE]
>
> 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`.

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
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.

> [!NOTE]
>
> `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 |

> [!WARNING]
>
> 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.

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
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.

> [!NOTE]
>
> 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.

> [!WARNING]
>
> 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.

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

```ini theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
<+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>
```

> [!WARNING]
>
> 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](https://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.

> [!WARNING]
>
> 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.


## Related topics

- [Special online services](https://dokumentation.websale.de/en/v8s/online-servicebereich/spezielle-online-dienste.md)
- [Directory structure of a shop](https://dokumentation.websale.de/en/v8s/materialien/verzeichnisstruktur-eines-shops.md)
- [Import file prod.cfg](https://dokumentation.websale.de/en/v8s/referenz/konfigurationen/importdatei-prod-cfg.md)
- [FAQ - Frequently asked questions](https://dokumentation.websale.de/en/faq-haufig-gestellte-fragen.md)
- [content - Catalogue (categories & products)](https://dokumentation.websale.de/en/konfiguration/content-katalog-kategorien-produkte.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.