Skip to content

Local UI to run and train LLMs and diffusion models. Supports GGUF, MLX, Qwen3.8, DeepSeek-V4.1, MiniMax-H3, Gemma 4, FLUX and more.

Studio: downscale oversized image uploads and add crop to image inputs (#13561)

Daniel Han7b3cb9fe86c2
diff --git a/studio/frontend/src/features/video/reference-image-editor.tsx b/studio/frontend/src/components/image-crop-editor.tsx
similarity index 95%
rename from studio/frontend/src/features/video/reference-image-editor.tsx
rename to studio/frontend/src/components/image-crop-editor.tsx
index b38cec96d18..9564dcba401 100644
--- a/studio/frontend/src/features/video/reference-image-editor.tsx
+++ b/studio/frontend/src/components/image-crop-editor.tsx
@@ -33,7 +33,7 @@ import {
moveCropRect,
rasterizeReferenceImageCrop,
referenceImageDataUrlError,
-} from "./reference-image-crop";
+} from "@/lib/image-crop";
type CropHandle = "north-west" | "north-east" | "south-west" | "south-east";
@@ -68,17 +68,19 @@ function arrowDelta(key: string, step: number): CropPoint | null {
return null;
}
-/** A local freeform crop editor for MiniMax-H3 picture references. */
+/** A local freeform crop editor for MiniMax-H3 picture references and image page inputs. */
export function ReferenceImageEditor({
open,
picture,
pictureNumber,
+ subject,
onOpenChange,
onApply,
}: {
open: boolean;
picture: StagedReferenceImage | null;
- pictureNumber: number;
+ pictureNumber?: number;
+ subject?: string;
onOpenChange: (open: boolean) => void;
onApply: (dataUrl: string, crop: CropRect | null) => void;
}) {
@@ -98,6 +100,10 @@ export function ReferenceImageEditor({
message: string;
} | null>(null);
const [applying, setApplying] = useState(false);
+ const name = subject
+ ? subject.charAt(0).toLowerCase() + subject.slice(1)
+ : `Picture ${pictureNumber ?? 1}`;
+ const lowerName = name.charAt(0).toLowerCase() + name.slice(1);
const editorActions = useMemo(
() => createReferenceImageEditorActions({ onApply, onOpenChange }),
[onApply, onOpenChange],
@@ -300,7 +306,7 @@ export function ReferenceImageEditor({
>
<DialogContent className="sm:max-w-3xl">
<DialogHeader>
- <DialogTitle>Crop Picture {pictureNumber}</DialogTitle>
+ <DialogTitle>Crop {name}</DialogTitle>
<DialogDescription>
Drag over the picture to choose what to keep. Move the selection or
resize it from its corners. Choose Use full image to clear any crop.
@@ -313,7 +319,7 @@ export function ReferenceImageEditor({
<div className="relative inline-block max-h-full max-w-full shrink-0">
<img
src={picture.originalDataUrl}
- alt={`Crop source ${pictureNumber}`}
+ alt={subject ? `Crop source for ${lowerName}` : `Crop source ${pictureNumber}`}
draggable={false}
className="block max-h-[48vh] max-w-full select-none object-contain"
/>
@@ -321,7 +327,7 @@ export function ReferenceImageEditor({
<div
role="group"
tabIndex={0}
- aria-label={`Crop selection for picture ${pictureNumber}. Drag to select an area. Drag the selection to move it, or drag a corner to resize it.`}
+ aria-label={`Crop selection for ${lowerName}. Drag to select an area. Drag the selection to move it, or drag a corner to resize it.`}
onPointerDown={handlePointerDown}
onPointerMove={handlePointerMove}
onPointerUp={finishPointer}
diff --git a/studio/frontend/src/components/image-dropzone.tsx b/studio/frontend/src/components/image-dropzone.tsx
index 6dc12b9b8e0..e98d0ba5579 100644
--- a/studio/frontend/src/components/image-dropzone.tsx
+++ b/studio/frontend/src/components/image-dropzone.tsx
@@ -2,7 +2,7 @@
// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
import { useCallback, useEffect, useRef, useState } from "react";
-import { Delete02Icon, ImageAdd02Icon } from "@hugeicons/core-free-icons";
+import { Delete02Icon, ImageAdd02Icon, ImageCropIcon } from "@hugeicons/core-free-icons";
import { HugeiconsIcon } from "@hugeicons/react";
import { Button } from "@/components/ui/button";
@@ -16,6 +16,8 @@ import {
registerNativeAttachmentPath,
useNativeDropTarget,
} from "@/features/native-intents";
+import { useImageCrop } from "@/hooks/use-image-crop";
+import { MAX_UPLOAD_IMAGE_SIDE, fitImageDataUrl } from "@/lib/image-fit";
import { cn } from "@/lib/utils";
import { toast } from "@/lib/toast";
@@ -28,6 +30,8 @@ export function ImageDropzone({
label = "Click or drop an image",
removeLabel = "Remove source image",
className,
+ maxSide = MAX_UPLOAD_IMAGE_SIDE,
+ cropSubject,
}: {
value: string | null;
onChange: (dataUrl: string | null) => void;
@@ -36,6 +40,9 @@ export function ImageDropzone({
/** Accessible remove-button name. */
removeLabel?: string;
className?: string;
+ /** Larger uploads are downscaled to this per side; null keeps them as chosen. */
+ maxSide?: number | null;
+ cropSubject?: string;
}) {
const inputRef = useRef<HTMLInputElement | null>(null);
const [dragging, setDragging] = useState(false);
@@ -70,14 +77,20 @@ export function ImageDropzone({
selection.current += 1;
const claimed = selection.current;
const reader = new FileReader();
- reader.onload = () => {
+ reader.onload = async () => {
if (claimed !== selection.current) return;
- onChange(typeof reader.result === "string" ? reader.result : null);
+ if (typeof reader.result !== "string") {
+ onChange(null);
+ return;
+ }
+ const dataUrl = maxSide ? await fitImageDataUrl(reader.result, maxSide) : reader.result;
+ if (!mounted.current || claimed !== selection.current) return;
+ onChange(dataUrl);
};
reader.onerror = () => toast.error("Could not read the image");
reader.readAsDataURL(file);
},
- [onChange],
+ [onChange, maxSide],
);
// Tauri suppresses the webview drop event, so desktop drops arrive as paths
@@ -97,15 +110,27 @@ export function ImageDropzone({
const intent = await registerNativeAttachmentPath(path);
const file = await readNativeAttachmentFile(intent.path.token);
if (!mounted.current || claimed !== selection.current) return;
- onChange(`data:${file.mimeType};base64,${file.base64}`);
+ const raw = `data:${file.mimeType};base64,${file.base64}`;
+ const dataUrl = maxSide ? await fitImageDataUrl(raw, maxSide) : raw;
+ if (!mounted.current || claimed !== selection.current) return;
+ onChange(dataUrl);
} catch (error) {
toast.error("Could not read the image", {
description: error instanceof Error ? error.message : String(error),
});
}
},
+ [onChange, maxSide],
+ );
+
+ const applyCrop = useCallback(
+ (dataUrl: string) => {
+ selection.current += 1;
+ onChange(dataUrl);
+ },
[onChange],
);
+ const { openCrop, cropDialog } = useImageCrop(value, applyCrop, cropSubject ?? "");
const nativeDropRef = useNativeDropTarget({
onDrop: (paths) => void readNativePath(paths[0]),
@@ -129,6 +154,26 @@ export function ImageDropzone({
backgroundSize: "16px 16px",
}}
/>
+ {cropSubject && (
+ <>
+ <Tooltip>
+ <TooltipTrigger asChild={true}>
+ <Button
+ type="button"
+ variant="secondary"
+ size="icon"
+ aria-label={`Crop ${cropSubject.charAt(0).toLowerCase()}${cropSubject.slice(1)}`}
+ className="absolute right-10 top-1.5 size-7"
+ onClick={openCrop}
+ >
+ <HugeiconsIcon icon={ImageCropIcon} className="size-3.5" />
+ </Button>
+ </TooltipTrigger>
+ <TooltipContent>Crop</TooltipContent>
+ </Tooltip>
+ {cropDialog}
+ </>
+ )}
<Tooltip>
<TooltipTrigger asChild={true}>
<Button
diff --git a/studio/frontend/src/features/images/images-page.tsx b/studio/frontend/src/features/images/images-page.tsx
index e54b8dbf272..b8dcc466f98 100644
--- a/studio/frontend/src/features/images/images-page.tsx
+++ b/studio/frontend/src/features/images/images-page.tsx
@@ -23,6 +23,7 @@ import {
FolderAddIcon,
Image03Icon,
ImageAdd02Icon,
+ ImageCropIcon,
InformationCircleIcon,
SparklesIcon,
} from "@hugeicons/core-free-icons";
@@ -32,6 +33,7 @@ import { MediaViewer } from "@/components/media-viewer";
import { shortPrompt } from "@/lib/prompt-text";
import { ImageDropzone } from "@/components/image-dropzone";
+import { useImageCrop } from "@/hooks/use-image-crop";
import { GuidedTour, useGuidedTourController } from "@/features/tour";
import { buildImagesTourSteps } from "./tour";
import { Button } from "@/components/ui/button";
@@ -3098,6 +3100,11 @@ export function ImagesPage({
setMaskImage(null);
setMaskResetKey((k) => k + 1);
}, []);
+ const { openCrop: openInpaintCrop, cropDialog: inpaintCropDialog } = useImageCrop(
+ initImage,
+ handleInitChange,
+ "Source image",
+ );
// Downloads go through the Hub download manager like every other model, so the load finds a
// warm cache. In a ref, so the callback is not a render dep.
@@ -4014,6 +4021,7 @@ export function ImagesPage({
setReferenceImages((prev) => prev.map((p, j) => (j === i ? (v ?? "") : p)))
}
removeLabel={`Remove image ${numberOf(i)}`}
+ cropSubject={`Image ${numberOf(i)}`}
/>
<Button
type="button"
@@ -5050,7 +5058,7 @@ export function ImagesPage({
label="Source image"
hint="The image to transform. Generation redraws it guided by your prompt; the Strength below controls how far."
>
- <ImageDropzone value={initImage} onChange={handleInitChange} />
+ <ImageDropzone value={initImage} onChange={handleInitChange} cropSubject="Source image" />
</Field>
<SliderField
label="Strength"
@@ -5109,6 +5117,17 @@ export function ImagesPage({
<HugeiconsIcon icon={Delete02Icon} className="size-3.5" />
Clear mask
</Button>
+ <Button
+ type="button"
+ variant="secondary"
+ size="sm"
+ className="flex-1"
+ onClick={openInpaintCrop}
+ >
+ <HugeiconsIcon icon={ImageCropIcon} className="size-3.5" />
+ Crop
+ </Button>
+ {inpaintCropDialog}
<Button
type="button"
variant="secondary"
@@ -5140,7 +5159,7 @@ export function ImagesPage({
label="Source image"
hint="The image to outpaint. The canvas grows on the selected sides and the new area is filled from your prompt; the original is kept."
>
- <ImageDropzone value={initImage} onChange={handleInitChange} />
+ <ImageDropzone value={initImage} onChange={handleInitChange} cropSubject="Source image" />
</Field>
<SliderField
label="Expand by"
@@ -5192,7 +5211,7 @@ export function ImagesPage({
label="Source image"
hint="The image to upscale. It is enlarged by the factor below, then re-detailed at higher resolution guided by your prompt; keep the prompt describing the same content."
>
- <ImageDropzone value={initImage} onChange={handleInitChange} />
+ <ImageDropzone value={initImage} onChange={handleInitChange} cropSubject="Source image" />
</Field>
<SliderField
label="Scale"
@@ -5221,7 +5240,7 @@ export function ImagesPage({
label={unifiedEdit ? "Image 1" : "Reference image"}
hint="A reference the model draws on (subject, style, or composition) while generating a NEW image from your prompt at the size below. Unlike Transform, it is not a redraw of this image, so there is no strength."
>
- <ImageDropzone value={initImage} onChange={handleInitChange} />
+ <ImageDropzone value={initImage} onChange={handleInitChange} cropSubject={unifiedEdit ? "Image 1" : "Reference image"} />
</Field>
{renderAdditionalImages(
(i) => i + 2,
@@ -5237,7 +5256,7 @@ export function ImagesPage({
label="Source image"
hint="The image to edit. Describe the change in the prompt below (e.g. 'make it night', 'add a red hat', 'change the background to a beach')."
>
- <ImageDropzone value={initImage} onChange={handleInitChange} />
+ <ImageDropzone value={initImage} onChange={handleInitChange} cropSubject="Source image" />
</Field>
)}
@@ -5281,7 +5300,7 @@ export function ImagesPage({
label="Image 1 (source)"
hint="The image to edit. Describe the change in the instruction below; add more images to combine them, and refer to them as Image 2, Image 3 and so on."
>
- <ImageDropzone value={initImage} onChange={handleInitChange} />
+ <ImageDropzone value={initImage} onChange={handleInitChange} cropSubject="Image 1" />
</Field>
)}
{conditioning?.localized_edit_modes?.length ? (
@@ -5585,7 +5604,7 @@ export function ImagesPage({
</Select>
{controlnetId && (
<>
- <ImageDropzone value={controlImage} onChange={setControlImage} />
+ <ImageDropzone value={controlImage} onChange={setControlImage} cropSubject="Control image" />
<div className="flex items-center gap-2">
<span className="shrink-0 text-xs text-muted-foreground">Control type</span>
<Select value={controlType} onValueChange={setControlType}>
diff --git a/studio/frontend/src/features/video/video-page.tsx b/studio/frontend/src/features/video/video-page.tsx
index 5f04019d7b6..0fd880f3b65 100644
--- a/studio/frontend/src/features/video/video-page.tsx
+++ b/studio/frontend/src/features/video/video-page.tsx
@@ -190,8 +190,8 @@ import {
referenceImageDataUrls,
stageReferenceImage,
type StagedReferenceImage,
-} from "./reference-image-crop";
-import { ReferenceImageEditor } from "./reference-image-editor";
+} from "@/lib/image-crop";
+import { ReferenceImageEditor } from "@/components/image-crop-editor";
import { type ReferenceMedia, ReferenceMediaPicker } from "./reference-picker";
import {
defaultReferenceVideoTrim,
@@ -4045,6 +4045,8 @@ function VideoGenerator({
}
label="Add"
className="h-24"
+ // MiniMax-H3 references take up to 8192px and have their own crop and fit.
+ maxSide={null}
/>
</div>
)}
diff --git a/studio/frontend/src/hooks/use-image-crop.tsx b/studio/frontend/src/hooks/use-image-crop.tsx
new file mode 100644
index 00000000000..5c10adbc16e
--- /dev/null
+++ b/studio/frontend/src/hooks/use-image-crop.tsx
@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import { type ReactNode, useCallback, useMemo, useState } from "react";
+
+import { ReferenceImageEditor } from "@/components/image-crop-editor";
+import {
+ type CropRect,
+ type StagedReferenceImage,
+ stageReferenceImage,
+} from "@/lib/image-crop";
+
+// Uploads keyed by their crop, outside any picker: a workflow switch remounts it, and a re-crop must start from the upload.
+const cropOrigins = new Map<string, StagedReferenceImage>();
+const MAX_CROP_ORIGINS = 8;
+
+function rememberCrop(entry: StagedReferenceImage) {
+ cropOrigins.delete(entry.dataUrl);
+ cropOrigins.set(entry.dataUrl, entry);
+ for (const key of cropOrigins.keys()) {
+ if (cropOrigins.size <= MAX_CROP_ORIGINS) break;
+ cropOrigins.delete(key);
+ }
+}
+
+export function useImageCrop(
+ value: string | null,
+ onChange: (dataUrl: string) => void,
+ subject: string,
+): { openCrop: () => void; cropDialog: ReactNode } {
+ // Keyed to the value it opened on, so a replaced or removed image closes it.
+ const [cropFor, setCropFor] = useState<string | null>(null);
+ const picture = useMemo(
+ () => (value ? (cropOrigins.get(value) ?? stageReferenceImage(value)) : null),
+ [value],
+ );
+ const apply = useCallback(
+ (dataUrl: string, crop: CropRect | null) => {
+ if (!picture) return;
+ rememberCrop({ originalDataUrl: picture.originalDataUrl, dataUrl, crop });
+ onChange(dataUrl);
+ },
+ [onChange, picture],
+ );
+ const openCrop = useCallback(() => setCropFor(value), [value]);
+ const cropDialog =
+ value !== null && cropFor === value ? (
+ <ReferenceImageEditor
+ open={true}
+ picture={picture}
+ subject={subject}
+ onOpenChange={(open) => setCropFor(open ? value : null)}
+ onApply={apply}
+ />
+ ) : null;
+ return { openCrop, cropDialog };
+}
diff --git a/studio/frontend/src/features/video/reference-image-crop.ts b/studio/frontend/src/lib/image-crop.ts
similarity index 100%
rename from studio/frontend/src/features/video/reference-image-crop.ts
rename to studio/frontend/src/lib/image-crop.ts
diff --git a/studio/frontend/src/lib/image-fit.ts b/studio/frontend/src/lib/image-fit.ts
new file mode 100644
index 00000000000..c9768cffed7
--- /dev/null
+++ b/studio/frontend/src/lib/image-fit.ts
@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+// decode_b64_image (studio/backend/core/inference/diffusion.py) refuses a source image above this per side.
+export const MAX_UPLOAD_IMAGE_SIDE = 4096;
+// DiffusionGenerateRequest.init_image max_length (studio/backend/models/inference.py).
+const MAX_UPLOAD_DATA_URL_LENGTH = 32 * 1024 * 1024;
+
+export function fitWithinMaxSide(
+ width: number,
+ height: number,
+ maxSide: number,
+): { width: number; height: number } | null {
+ const longest = Math.max(width, height);
+ if (!(width > 0 && height > 0 && longest > maxSide)) return null;
+ const scale = maxSide / longest;
+ return {
+ width: Math.min(maxSide, Math.max(1, Math.round(width * scale))),
+ height: Math.min(maxSide, Math.max(1, Math.round(height * scale))),
+ };
+}
+
+/** JPEG only for a JPEG source: a JPEG export paints transparent pixels black. */
+export function fitOutputType(dataUrl: string): "image/jpeg" | "image/png" {
+ return /^data:image\/(jpeg|jpg|pjpeg)[;,]/i.test(dataUrl) ? "image/jpeg" : "image/png";
+}
+
+/** Anything that fits, or that this browser cannot decode, is returned unchanged so the server still reports it. */
+export async function fitImageDataUrl(dataUrl: string, maxSide: number): Promise<string> {
+ let image: HTMLImageElement;
+ try {
+ image = await new Promise<HTMLImageElement>((resolve, reject) => {
+ const img = new Image();
+ img.onload = () => resolve(img);
+ img.onerror = reject;
+ img.src = dataUrl;
+ });
+ } catch {
+ return dataUrl;
+ }
+ // naturalWidth/Height and drawImage both follow EXIF orientation, so the result is upright.
+ const size = fitWithinMaxSide(image.naturalWidth, image.naturalHeight, maxSide);
+ if (!size) return dataUrl;
+ const canvas = document.createElement("canvas");
+ canvas.width = size.width;
+ canvas.height = size.height;
+ const context = canvas.getContext("2d");
+ if (!context) return dataUrl;
+ context.imageSmoothingQuality = "high";
+ context.drawImage(image, 0, 0, size.width, size.height);
+ const type = fitOutputType(dataUrl);
+ let fitted = canvas.toDataURL(type, 0.92);
+ // A photographic 4096px PNG can pass the request cap; WebP keeps alpha at a fraction of the size.
+ if (type === "image/png" && fitted.length > MAX_UPLOAD_DATA_URL_LENGTH) {
+ fitted = canvas.toDataURL("image/webp", 0.92);
+ }
+ return fitted.startsWith("data:image/") ? fitted : dataUrl;
+}
diff --git a/studio/frontend/tests/image-fit.test.ts b/studio/frontend/tests/image-fit.test.ts
new file mode 100644
index 00000000000..1528df6fd04
--- /dev/null
+++ b/studio/frontend/tests/image-fit.test.ts
@@ -0,0 +1,48 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// Copyright 2026-present the Unsloth AI Inc. team. All rights reserved. See /studio/LICENSE.AGPL-3.0
+
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import test from "node:test";
+
+import {
+ MAX_UPLOAD_IMAGE_SIDE,
+ fitOutputType,
+ fitWithinMaxSide,
+} from "../src/lib/image-fit.ts";
+
+test("the upload cap matches the backend decode limit", () => {
+ const backend = readFileSync(
+ new URL("../../backend/core/inference/diffusion.py", import.meta.url),
+ "utf8",
+ );
+ const match = /def decode_b64_image\([\s\S]*?max_side: int = (\d+)/.exec(backend);
+ assert.ok(match, "decode_b64_image max_side default not found");
+ assert.equal(MAX_UPLOAD_IMAGE_SIDE, Number(match[1]));
+});
+
+test("a 24MP iPhone photo is scaled to fit at the same aspect", () => {
+ assert.deepEqual(fitWithinMaxSide(5712, 4284, 4096), { width: 4096, height: 3072 });
+ assert.deepEqual(fitWithinMaxSide(4284, 5712, 4096), { width: 3072, height: 4096 });
+ assert.deepEqual(fitWithinMaxSide(8064, 6048, 4096), { width: 4096, height: 3072 });
+});
+
+test("images that already fit are left alone, so a second pass is a no-op", () => {
+ assert.equal(fitWithinMaxSide(4032, 3024, 4096), null);
+ assert.equal(fitWithinMaxSide(4096, 4096, 4096), null);
+ const once = fitWithinMaxSide(9999, 7777, 4096);
+ assert.ok(once);
+ assert.equal(fitWithinMaxSide(once.width, once.height, 4096), null);
+});
+
+test("extreme aspects never round to zero or past the cap", () => {
+ assert.deepEqual(fitWithinMaxSide(20000, 3, 4096), { width: 4096, height: 1 });
+ assert.equal(fitWithinMaxSide(0, 5000, 4096), null);
+});
+
+test("only JPEG sources are re-encoded as JPEG", () => {
+ assert.equal(fitOutputType("data:image/jpeg;base64,AAAA"), "image/jpeg");
+ assert.equal(fitOutputType("data:image/png;base64,AAAA"), "image/png");
+ assert.equal(fitOutputType("data:image/webp;base64,AAAA"), "image/png");
+ assert.equal(fitOutputType("data:image/gif;base64,AAAA"), "image/png");
+});
diff --git a/studio/frontend/tests/video-reference-image-crop.test.ts b/studio/frontend/tests/video-reference-image-crop.test.ts
index 2aba38b6bb8..9178e642c77 100644
--- a/studio/frontend/tests/video-reference-image-crop.test.ts
+++ b/studio/frontend/tests/video-reference-image-crop.test.ts
@@ -19,7 +19,7 @@ import {
referenceImageDataUrlError,
referenceImageDataUrls,
stageReferenceImage,
-} from "../src/features/video/reference-image-crop.ts";
+} from "../src/lib/image-crop.ts";
test("crop rectangles stay within natural image pixels in either drag direction", () => {
assert.deepEqual(