# Skalierung & Zuschnitt

Diese Seite dokumentiert alle Operationen zur Steuerung von Bildabmessungen, Seitenverhältnis, Zuschnitt und Positionierung.

### Resize

```
rs:%resizing_type:%width:%height:%enlarge:%extend
```

Die Haupt-Skalierungsoperation. Kombiniert Skalierungstyp, Breite, Höhe, Enlarge und Extend in einer einzigen Anweisung. Alle Parameter sind optional und können weggelassen werden, um die Standardwerte zu verwenden.

| Parameter      | Typ      | Standard       | Erlaubte Werte                                        |
| -------------- | -------- | -------------- | ----------------------------------------------------- |
| resizing\_type | string   | `fit`          | `fit`, `fill`, `fill-down`, `force`, `auto`           |
| width          | integer  | `0`            | Beliebige positive Ganzzahl, oder `0` für automatisch |
| height         | integer  | `0`            | Beliebige positive Ganzzahl, oder `0` für automatisch |
| enlarge        | boolean  | `false`        | `1`, `t`, `true` zum Aktivieren                       |
| extend         | compound | `false:ce:0:0` | Siehe [Extend](#extend)                               |

**Beispiele:**

```
# In 300x200 einpassen, Seitenverhältnis beibehalten
rs:fit:300:200

# Exakt 400x400 ausfüllen, Überschuss abschneiden
rs:fill:400:400

# Exakte Abmessungen erzwingen (kann verzerren)
rs:force:500:300

# In 300x200 einpassen, kleine Bilder vergrößern erlaubt
rs:fit:300:200:1
```

**Rewrite-Rule-Beispiel:**

Regex: `^/thumb/(\d+)x(\d+)/(.*)` Target: `/_sx/img/_/rs:fit:$1:$2/q:80/plain/$3`

***

### Size

```
s:%width:%height:%enlarge:%extend
```

Kurzform für Breite, Höhe, Enlarge und Extend — ohne Angabe eines Skalierungstyps. Es wird der aktuelle Skalierungstyp verwendet (Standard: `fit`).

| Parameter | Typ      | Standard       | Erlaubte Werte                                        |
| --------- | -------- | -------------- | ----------------------------------------------------- |
| width     | integer  | `0`            | Beliebige positive Ganzzahl, oder `0` für automatisch |
| height    | integer  | `0`            | Beliebige positive Ganzzahl, oder `0` für automatisch |
| enlarge   | boolean  | `false`        | `1`, `t`, `true` zum Aktivieren                       |
| extend    | compound | `false:ce:0:0` | Siehe [Extend](#extend)                               |

**Beispiel:**

```
s:300:200
```

***

### Resizing Type

```
rt:%resizing_type
```

Definiert, wie smoxy das Quellbild skaliert. Kann unabhängig oder als Teil der `rs`-Operation gesetzt werden.

| Parameter      | Typ    | Standard | Erlaubte Werte                              |
| -------------- | ------ | -------- | ------------------------------------------- |
| resizing\_type | string | `fit`    | `fit`, `fill`, `fill-down`, `force`, `auto` |

#### Skalierungstypen im Detail

| Typ         | Verhalten                                                                                                                                                                                     |
| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fit`       | Skaliert das Bild unter Beibehaltung des Seitenverhältnisses, sodass es vollständig in die angegebenen Abmessungen passt. Das Ergebnis ist gleich groß oder kleiner als die angegebene Größe. |
| `fill`      | Skaliert das Bild unter Beibehaltung des Seitenverhältnisses, sodass es die angegebenen Abmessungen vollständig ausfüllt. Überstehende Teile werden abgeschnitten.                            |
| `fill-down` | Wie `fill`, aber wenn das skalierte Bild kleiner als die gewünschte Größe ist, wird das Ergebnis zugeschnitten, um das gewünschte Seitenverhältnis beizubehalten.                             |
| `force`     | Skaliert auf die exakten Abmessungen ohne Beibehaltung des Seitenverhältnisses. Das Bild kann dadurch verzerrt werden.                                                                        |
| `auto`      | Wenn Quell- und Ergebnisbild die gleiche Ausrichtung haben (beide Hochformat oder beide Querformat), wird `fill` verwendet. Andernfalls wird `fit` verwendet.                                 |

**Beispiel:**

```
rt:fill
```

***

### Width

```
w:%width
```

Setzt die Breite des Ergebnisbildes unabhängig. Bei `0` berechnet smoxy die Breite aus der definierten Höhe und dem Seitenverhältnis des Quellbildes.

| Parameter | Typ     | Standard | Erlaubte Werte                                        |
| --------- | ------- | -------- | ----------------------------------------------------- |
| width     | integer | `0`      | Beliebige positive Ganzzahl, oder `0` für automatisch |

**Beispiel:**

```
# Auf 600px Breite skalieren, Höhe wird automatisch berechnet
w:600
```

**Rewrite-Rule-Beispiel:**

Regex: `^/w/(\d+)/(.*)` Target: `/_sx/img/_/w:$1/q:80/plain/$2`

Eine Anfrage an `/w/800/media/photo.jpg` skaliert das Bild auf 800px Breite.

***

### Height

```
h:%height
```

Setzt die Höhe des Ergebnisbildes unabhängig. Bei `0` berechnet smoxy die Höhe aus der definierten Breite und dem Seitenverhältnis des Quellbildes.

| Parameter | Typ     | Standard | Erlaubte Werte                                        |
| --------- | ------- | -------- | ----------------------------------------------------- |
| height    | integer | `0`      | Beliebige positive Ganzzahl, oder `0` für automatisch |

**Beispiel:**

```
h:400
```

***

### Min Width

```
mw:%width
```

Definiert die Mindestbreite des Ergebnisbildes.

| Parameter | Typ     | Standard | Erlaubte Werte                                         |
| --------- | ------- | -------- | ------------------------------------------------------ |
| width     | integer | `0`      | Beliebige positive Ganzzahl, oder `0` zum Deaktivieren |

{% hint style="warning" %}
**Wichtig:** Wenn sowohl `w` als auch `mw` gesetzt sind, wird das endgültige Bild gemäß `w` zugeschnitten. Diese Kombination sollte mit Vorsicht verwendet werden.
{% endhint %}

**Beispiel:**

```
mw:200
```

***

### Min Height

```
mh:%height
```

Definiert die Mindesthöhe des Ergebnisbildes.

| Parameter | Typ     | Standard | Erlaubte Werte                                         |
| --------- | ------- | -------- | ------------------------------------------------------ |
| height    | integer | `0`      | Beliebige positive Ganzzahl, oder `0` zum Deaktivieren |

{% hint style="warning" %}
**Wichtig:** Wenn sowohl `h` als auch `mh` gesetzt sind, wird das endgültige Bild gemäß `h` zugeschnitten. Diese Kombination sollte mit Vorsicht verwendet werden.
{% endhint %}

**Beispiel:**

```
mh:200
```

***

### Enlarge

```
el:%enlarge
```

Steuert, ob smoxy Bilder vergrößert, die kleiner als die Zielabmessungen sind.

| Parameter | Typ     | Standard | Erlaubte Werte                                                      |
| --------- | ------- | -------- | ------------------------------------------------------------------- |
| enlarge   | boolean | `false`  | `1`, `t`, `true` zum Aktivieren; `0`, `f`, `false` zum Deaktivieren |

Standardmäßig werden Bilder, die kleiner als die angeforderte Größe sind, nicht hochskaliert. Diese Option aktivieren, wenn das Bild immer den angeforderten Abmessungen entsprechen soll.

**Beispiel:**

```
# Vergrößerung erlauben
el:1
```

***

### Extend

```
ex:%extend:%gravity
```

Wenn aktiviert und das skalierte Bild kleiner als die Zielabmessungen ist, wird die Leinwand auf die gewünschte Größe erweitert. Der erweiterte Bereich wird mit der [Hintergrundfarbe](https://docs.smoxy.eu/effekte-and-anpassungen#background) gefüllt.

| Parameter | Typ     | Standard | Erlaubte Werte                            |
| --------- | ------- | -------- | ----------------------------------------- |
| extend    | boolean | `false`  | `1`, `t`, `true` zum Aktivieren           |
| gravity   | string  | `ce:0:0` | Jeder [Gravity](#gravity)-Wert außer `sm` |

**Beispiel:**

```
# Leinwand erweitern, Bild oben platzieren
ex:1:no

# Leinwand erweitern, Bild zentrieren (Standard)
ex:1:ce
```

***

### Extend Aspect Ratio

```
exar:%extend:%gravity
```

Wenn aktiviert, wird die Leinwand des Bildes erweitert, um das gewünschte Seitenverhältnis zu erreichen. Der zusätzliche Bereich wird mit der Hintergrundfarbe gefüllt.

| Parameter | Typ     | Standard | Erlaubte Werte                            |
| --------- | ------- | -------- | ----------------------------------------- |
| extend    | boolean | `false`  | `1`, `t`, `true` zum Aktivieren           |
| gravity   | string  | `ce:0:0` | Jeder [Gravity](#gravity)-Wert außer `sm` |

**Beispiel:**

```
exar:1:ce
```

***

### Zoom

```
z:%zoom_x_y
z:%zoom_x:%zoom_y
```

Multipliziert die Bildabmessungen mit dem angegebenen Faktor. Kann mit `w` und `h` kombiniert werden — smoxy berechnet zuerst die Größe aus Breite/Höhe und multipliziert dann mit dem Zoom-Faktor.

| Parameter  | Typ   | Standard | Erlaubte Werte                                     |
| ---------- | ----- | -------- | -------------------------------------------------- |
| zoom\_x\_y | float | `1`      | Beliebiger Wert > 0 (einheitlich für beide Achsen) |
| zoom\_x    | float | `1`      | Beliebiger Wert > 0                                |
| zoom\_y    | float | `1`      | Beliebiger Wert > 0                                |

{% hint style="info" %}
**Hinweis:** Im Gegensatz zu `dpr` beeinflusst die `zoom`-Option **keine** Gravity-Offsets, Wasserzeichen-Offsets oder Padding-Werte.
{% endhint %}

**Beispiele:**

```
# Abmessungen verdoppeln
z:2

# 1,5× Breite, 2× Höhe
z:1.5:2
```

***

### DPR (Device Pixel Ratio)

```
dpr:%dpr
```

Multipliziert die Bildabmessungen mit dem angegebenen Faktor für HiDPI-(Retina-)Displays.

| Parameter | Typ   | Standard | Erlaubte Werte      |
| --------- | ----- | -------- | ------------------- |
| dpr       | float | `1`      | Beliebiger Wert > 0 |

{% hint style="info" %}
**Hinweis:** Im Gegensatz zu `zoom` beeinflusst die `dpr`-Option Gravity-Offsets, Wasserzeichen-Offsets und Padding-Werte **mit**. Das stellt sicher, dass die Struktur des Ergebnisbildes mit und ohne `dpr` konsistent bleibt.
{% endhint %}

**Beispiel:**

```
dpr:2
```

***

### Gravity

```
g:%type:%x_offset:%y_offset
```

Steuert, worauf smoxy beim Beschneiden von Bildteilen fokussiert (verwendet bei `fill`-Skalierung, `crop` und `extend`).

| Parameter | Typ    | Standard | Erlaubte Werte                          |
| --------- | ------ | -------- | --------------------------------------- |
| type      | string | `ce`     | Siehe Tabelle unten                     |
| x\_offset | float  | `0`      | Absolute Pixel (≥ 1) oder relativ (< 1) |
| y\_offset | float  | `0`      | Absolute Pixel (≥ 1) oder relativ (< 1) |

#### Gravity-Typen

| Wert   | Position                    |
| ------ | --------------------------- |
| `ce`   | Mitte (Standard)            |
| `no`   | Norden — oberer Rand        |
| `so`   | Süden — unterer Rand        |
| `ea`   | Osten — rechter Rand        |
| `we`   | Westen — linker Rand        |
| `noea` | Nordost — obere rechte Ecke |
| `nowe` | Nordwest — obere linke Ecke |
| `soea` | Südost — untere rechte Ecke |
| `sowe` | Südwest — untere linke Ecke |

#### Spezielle Gravity-Typen

| Wert       | Beschreibung                                                                                                                                                      |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sm`       | Smart Gravity — erkennt automatisch den „interessantesten" Bereich des Bildes und verwendet ihn als Mittelpunkt. Offsets sind hier nicht anwendbar.               |
| `fp:%x:%y` | Fokuspunkt — `x` und `y` sind Gleitkommazahlen zwischen 0 und 1, die den Mittelpunkt des Ergebnisbildes definieren. `0:0` ist oben links, `1:1` ist unten rechts. |

**Beispiele:**

```
# Vom oberen Rand beschneiden
g:no

# Von unten rechts beschneiden, mit 10px Offset
g:soea:10:10

# Smart Crop
g:sm

# Fokuspunkt bei 30 % von links, 70 % von oben
g:fp:0.3:0.7
```

**Rewrite-Rule-Beispiel — Smart-Cropping-Thumbnails:**

Regex: `^/smart/(\d+)x(\d+)/(.*)` Target: `/_sx/img/_/rs:fill:$1:$2/g:sm/q:80/plain/$3`

***

### Crop

```
c:%width:%height:%gravity
```

Schneidet das Bild auf bestimmte Abmessungen zu — **vor** der Skalierung. Nützlich, um einen bestimmten Bereich aus dem Quellbild zu extrahieren.

| Parameter | Typ    | Standard                 | Erlaubte Werte                                                   |
| --------- | ------ | ------------------------ | ---------------------------------------------------------------- |
| width     | float  | erforderlich             | Absolute Pixel (≥ 1) oder relativ (0–1). `0` = volle Quellbreite |
| height    | float  | erforderlich             | Absolute Pixel (≥ 1) oder relativ (0–1). `0` = volle Quellhöhe   |
| gravity   | string | verwendet Gravity-Option | Jeder [Gravity](#gravity)-Wert                                   |

**Beispiele:**

```
# 500x300 aus der Mitte zuschneiden
c:500:300:ce

# Oberes linkes Viertel (50 % von Breite und Höhe)
c:0.5:0.5:nowe

# 800x600 von oben zuschneiden
c:800:600:no
```

***

### Trim

```
t:%threshold:%color:%equal_hor:%equal_ver
```

Entfernt umgebende Hintergrundpixel, die einer Zielfarbe ähnlich sind. Wenn keine Farbe angegeben wird, erkennt smoxy die Hintergrundfarbe automatisch.

| Parameter  | Typ        | Standard            | Erlaubte Werte                                                                                       |
| ---------- | ---------- | ------------------- | ---------------------------------------------------------------------------------------------------- |
| threshold  | float      | erforderlich        | Farbähnlichkeitstoleranz (beliebige positive Zahl)                                                   |
| color      | Hex-String | automatisch erkannt | 6-stelliger Hex-Farbwert ohne `#` (z. B. `ffffff`). `FF00FF` für transparente Hintergründe verwenden |
| equal\_hor | boolean    | `false`             | `1`, `t`, `true` — gleiche Menge links und rechts entfernen                                          |
| equal\_ver | boolean    | `false`             | `1`, `t`, `true` — gleiche Menge oben und unten entfernen                                            |

{% hint style="warning" %}
**Wichtig:** Trim erfordert, dass das gesamte Bild in den Arbeitsspeicher geladen wird. Das erhöht den Speicherverbrauch und die Verarbeitungszeit erheblich. Bei großen Bildern mit Vorsicht verwenden. Animierte Bilder werden nicht unterstützt.
{% endhint %}

{% hint style="info" %}
**Tipp:** Wenn die Hintergrundfarbe der Bilder bekannt ist, spart die explizite Angabe über den `color`-Parameter Ressourcen, da smoxy die Farbe nicht automatisch erkennen muss.
{% endhint %}

**Beispiele:**

```
# Hintergrund automatisch erkennen, Schwellenwert 10
t:10

# Weißen Hintergrund trimmen, gleichmäßig auf allen Seiten
t:10:ffffff:1:1

# Transparenten Hintergrund trimmen
t:10:FF00FF
```