Skip to content

Free, open-source AI video generator for Mac. Run LTX-2.5 and MiniMax H3 (Hailuo) locally on Apple Silicon: text-to-video and image-to-video with sound, lip-sync, character LoRA training, songs from lyrics (YuE2) and image editing (Qwen-Image-Edit). One-click install via Pinokio. Offline: no cloud, no API key, no NVIDIA GPU.

feat(train): letterbox crop strategy — preserve wide-shot proportions

mrbizarro7a46b96a4c56
diff --git a/lora_lab/train_character.py b/lora_lab/train_character.py
index 1a1bc9f..0a71225 100644
--- a/lora_lab/train_character.py
+++ b/lora_lab/train_character.py
@@ -267,8 +267,30 @@ def crop_and_caption(
trigger: str,
caption_strategy: str,
resolution: int,
+ crop_strategy: str = "center",
) -> tuple[list[Path], list[str]]:
- """Center-crop sources to `resolution`x`resolution`, rename sequentially, write captions.
+ """Scale + (optionally) crop sources to a `resolution`x`resolution` square,
+ rename sequentially, write captions.
+
+ `crop_strategy` ∈ {"center", "letterbox"} controls how non-square sources
+ fit into the square training canvas:
+
+ "center" (default, legacy behavior):
+ Scale so the SHORTER source dim = target, then center-crop the
+ longer dim to target. Image fills the square; content on the
+ longer dim is clipped. Good for character close-ups where the
+ face is centered. Bad for wide shots — long-shot proportions are
+ never seen by the model, which is why generated long shots tend
+ to look mushy / wrong-scale.
+
+ "letterbox":
+ Scale so the LONGER source dim = target, then pad the shorter
+ dim with black to fill the square. Image content keeps its
+ native aspect ratio inside the square. Model learns to ignore
+ the consistent black bars (they're a constant factor across
+ training samples). Trade-off: ~30% pixel-budget waste on bars
+ for portraits/landscapes, but generated long shots / wide
+ shots reproduce real proportions.
Returns (renamed_image_paths, caption_strings) in matching order.
@@ -283,7 +305,13 @@ def crop_and_caption(
captions_dir.mkdir(parents=True, exist_ok=True)
images_renamed_dir.mkdir(parents=True, exist_ok=True)
- emit("crop_start", total=len(source_files))
+ if crop_strategy not in ("center", "letterbox"):
+ raise ValueError(
+ f"unknown crop_strategy: {crop_strategy!r} "
+ f"(want 'center' or 'letterbox')"
+ )
+
+ emit("crop_start", total=len(source_files), crop_strategy=crop_strategy)
out_paths: list[Path] = []
out_captions: list[str] = []
@@ -292,21 +320,40 @@ def crop_and_caption(
try:
img = Image.open(src).convert("RGB")
src_w, src_h = img.size
-
- # Scale-and-center-crop to a SQUARE at `resolution`. Mirrors the
- # logic in preprocess_images._load_image_as_1frame_tensor (square
- # crop is the right call for char training — the preprocessor will
- # re-crop to whatever target_h/target_w is configured downstream;
- # we keep this square + lossless so the same source can be reused
- # for any preset).
target = resolution
- scale = max(target / src_w, target / src_h)
- new_w = int(round(src_w * scale))
- new_h = int(round(src_h * scale))
- scaled = img.resize((new_w, new_h), Image.LANCZOS)
- left = (new_w - target) // 2
- top = (new_h - target) // 2
- cropped_full = scaled.crop((left, top, left + target, top + target))
+
+ if crop_strategy == "letterbox":
+ # Scale so the LONGER source dim = target. Pad the shorter
+ # dim with black bars to fill the square. Trainer sees a
+ # uniform (target × target) canvas across all samples —
+ # preprocess + dataloader unchanged — but each image
+ # retains its native aspect ratio. Model learns the bars
+ # as a constant feature (they're identical across every
+ # training sample) and the actual subject geometry stays
+ # uncompressed.
+ scale = min(target / src_w, target / src_h)
+ new_w = int(round(src_w * scale))
+ new_h = int(round(src_h * scale))
+ scaled = img.resize((new_w, new_h), Image.LANCZOS)
+ cropped_full = Image.new("RGB", (target, target), (0, 0, 0))
+ paste_x = (target - new_w) // 2
+ paste_y = (target - new_h) // 2
+ cropped_full.paste(scaled, (paste_x, paste_y))
+ else:
+ # "center" — scale-and-center-crop to a SQUARE at
+ # `resolution`. Mirrors the logic in preprocess_images.
+ # _load_image_as_1frame_tensor (square crop is the right
+ # call for character training — the preprocessor will
+ # re-crop to whatever target_h/target_w is configured
+ # downstream; we keep this square + lossless so the same
+ # source can be reused for any preset).
+ scale = max(target / src_w, target / src_h)
+ new_w = int(round(src_w * scale))
+ new_h = int(round(src_h * scale))
+ scaled = img.resize((new_w, new_h), Image.LANCZOS)
+ left = (new_w - target) // 2
+ top = (new_h - target) // 2
+ cropped_full = scaled.crop((left, top, left + target, top + target))
stem = f"char_{i:03d}"
png_path = images_renamed_dir / f"{stem}.png"
@@ -660,12 +707,13 @@ def run_pipeline(spec_path: Path) -> int:
)
crop_strategy = advanced.get("crop_strategy") or "center"
- if crop_strategy != "center":
+ if crop_strategy not in ("center", "letterbox"):
emit(
"warning",
stage="crop",
message=f"crop_strategy={crop_strategy!r} not implemented; using center",
)
+ crop_strategy = "center"
# Validate resolution.
resolution = int(cfg["resolution"])
@@ -715,6 +763,7 @@ def run_pipeline(spec_path: Path) -> int:
trigger=trigger,
caption_strategy=caption_strategy,
resolution=resolution,
+ crop_strategy=crop_strategy,
)
except Exception as exc: # noqa: BLE001
traceback.print_exc(file=sys.stderr)
diff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.py
index a95cf1c..b788136 100644
--- a/mlx_ltx_panel.py
+++ b/mlx_ltx_panel.py
@@ -4123,6 +4123,22 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,
resolution = _int_or("resolution", cfg["resolution"])
caption_strategy = (f("caption_strategy", "trigger_simple")
or "trigger_simple").lower()
+ # Crop strategy for the training preprocess.
+ # "center" — current behavior, scale + center-crop to a square.
+ # Best for tightly-framed character close-ups; biases
+ # the model toward those framings.
+ # "letterbox" — preserve native aspect, pad with black bars to a
+ # square. Captures wide-shot / long-shot proportions
+ # the center-crop path destroys, at the cost of
+ # ~30% pixel-budget waste on bars for non-square
+ # sources. Salo flagged 2026-05-17: medium-long
+ # shots from center-crop-trained LoRAs come out
+ # blurry because the model never saw those
+ # proportions during training.
+ crop_strategy = (f("crop_strategy", "center")
+ or "center").lower()
+ if crop_strategy not in ("center", "letterbox"):
+ crop_strategy = "center"
eta_sec = _train_estimate_seconds(preset, image_count,
steps_override=steps,
is_style=is_style)
@@ -4169,6 +4185,7 @@ def make_job(form: dict[str, list[str]] | dict[str, str], *,
"lr": lr,
"resolution": resolution,
"caption_strategy": caption_strategy,
+ "crop_strategy": crop_strategy,
"image_count": image_count,
"eta_sec": eta_sec,
"ram_peak_gb": cfg["ram_peak_gb"],
@@ -4990,6 +5007,7 @@ def run_train_job_inner(job: dict) -> None:
"lr": p.get("lr"),
"resolution": p.get("resolution"),
"caption_strategy": caption_strategy,
+ "crop_strategy": p.get("crop_strategy", "center"),
"images_dir": str(images_dir),
"captions_dir": str(captions_dir),
"checkpoints_dir": str(dataset_dir / "checkpoints"),
@@ -16763,6 +16781,29 @@ HTML = r"""<!doctype html>
<button type="button" class="pill-btn" data-train-preset="high"><span>High</span><span class="sub" id="trainPresetHighSub">~2 h 50 min · rank 32 · 5000 steps · 512px</span></button>
</div>
+ <!-- Crop strategy — primary control (not buried in Advanced) because
+ it has a big visible effect on what the model learns. Salo 2026-05-17:
+ "we are using such a limited cropping of the images, all the images
+ are kind of close-up medium close-ups. That's the reason why the
+ medium long shots are so shit and blurry." Letterbox preserves
+ wide-shot proportions at the cost of pixel-budget waste on black
+ bars. The trainer sees a uniform square canvas either way, so
+ this doesn't change wall time or memory. -->
+ <h2 style="margin-top:14px">Crop strategy
+ <span class="h2-hint">how non-square images fit the training canvas</span>
+ </h2>
+ <div class="pill-group cols-2" id="trainCropStrategyGroup">
+ <button type="button" class="pill-btn active" data-train-crop="center">
+ <span>Center crop</span>
+ <span class="sub">scale + crop to square · best for tight portraits</span>
+ </button>
+ <button type="button" class="pill-btn" data-train-crop="letterbox">
+ <span>Letterbox <span class="rec-badge" style="background:rgba(94,234,255,0.18);color:var(--accent-bright)">Preserve aspect</span></span>
+ <span class="sub">pad with black · keeps wide-shot proportions</span>
+ </button>
+ </div>
+ <input type="hidden" name="crop_strategy" id="trainCropStrategy" value="center">
+
<details class="train-advanced">
<summary>Advanced</summary>
<div class="train-advanced-grid">
@@ -19125,6 +19166,19 @@ function trainWirePresetButtons() {
trainUpdateEstimate();
});
});
+ // Crop strategy pills — same click pattern. Updates the hidden
+ // #trainCropStrategy input which rides the form on submit. No estimate
+ // change because letterbox uses the same square canvas as center crop;
+ // wall time + memory are unaffected.
+ document.querySelectorAll('#trainCropStrategyGroup .pill-btn').forEach(b => {
+ b.addEventListener('click', () => {
+ const v = b.dataset.trainCrop;
+ const inp = document.getElementById('trainCropStrategy');
+ if (inp) inp.value = v;
+ document.querySelectorAll('#trainCropStrategyGroup .pill-btn').forEach(x =>
+ x.classList.toggle('active', x === b));
+ });
+ });
}
function trainWireAdvancedFields() {
@@ -19622,6 +19676,9 @@ async function trainStart() {
fd.set('preset', TRAIN.preset);
fd.set('image_count', String(TRAIN.images.length));
fd.set('caption_strategy', captionStrategy);
+ // Crop strategy chip — center (default) or letterbox.
+ const cropInp = document.getElementById('trainCropStrategy');
+ if (cropInp && cropInp.value) fd.set('crop_strategy', cropInp.value);
const rank = document.getElementById('trainRank').value;
if (rank) fd.set('rank', rank);
const stepsVal = document.getElementById('trainSteps').value;