IMBlueprint — User Manual

IMBlueprint is a smart, zero-dependency command line builder for ImageMagick 7. It comes as a single, portable HTML file that works 100% offline in any browser. Please note: IMBlueprint only generates the text commands. You still need ImageMagick installed on your system to actually process your images. It covers everything from simple format conversion to resize/crop pipelines, color grading, watermarks, and whole-folder batch runs — always emitting the real ImageMagick 7 flags in a pipeline order that works.

Special features

What sets this builder apart from other ImageMagick command generators:

• Resize modes done right. Fit keeps the aspect ratio inside the box (-resize 1280x720), Long side sets the longer edge to a fixed length (-resize "1920x1920>") — one setting for folders mixing portrait and landscape shots — Stretch forces the exact size (!), Cover fills the box and crops the overflow from the center (-resize "1280x720^" + -gravity center -extent), and Percent scales proportionally. Fill only one side and the other follows the aspect ratio (-resize 1280x) — and once Analyze Image knows the source size, the builder even shows the resulting other dimension, e.g. ≈ height 960 px. Geometry modifiers (^, !, >) are emitted quoted, because cmd.exe treats ^ as an escape character and every shell treats an unquoted > as a redirect.
• Per-format quality that adapts. The quality slider's range, default and hint follow the output format: JPEG 92, WebP 80 (+ lossless define), AVIF 65, HEIC 85. PNG switches to a compression-level select (-define png:compression-level), TIFF to a compress select (zip/lzw/jpeg/none) — no invalid quality flags for lossless formats.
• Format rules instead of broken output. Switching the format renames the output extension, and formats without an alpha channel (JPEG, BMP) auto-enable Flatten transparency so PNG→JPEG conversions never end in black corners. GIF/AVIF/HEIC carry hints about their limits and delegate requirements.
• Watermarks with real compositing. Text overlays use -gravity + -annotate with fill/outline colors and offsets; image overlays use a parenthesized group with alpha-channel opacity (-channel A -evaluate multiply) and -composite. The parentheses are escaped for the selected target shell — ^( … ^) for cmd.exe, "(" … ")" for PowerShell, \( … \) for bash — so Copy always yields runnable syntax.
• Target-shell switch. The command box and its Copy button always match the selected shell: Windows CMD, PowerShell, or macOS/Linux bash. The default follows the platform the tool is opened on. The .bat / .sh downloads are converted to their matching shell automatically, independent of what is currently displayed.
• Whole-folder batch mode. A one-click switch from magick to magick mogrify -path <output folder> -format png … "*.jpg" processes every matching file, converts it to the chosen output format (mogrify would otherwise keep the source format), and writes the results elsewhere. Originals stay untouched as long as the output folder differs from the input folder — the builder warns if the two are the same, since mogrify would then overwrite the files in place. Watermarks are correctly disabled in batch mode (mogrify cannot composite a second image).
• Analyze Image → source info. Builds the magick identify -verbose command for you; paste the output and the image is listed in a table (format, dimensions, colorspace, type, depth, quality, filesize, resolution, camera + EXIF exposure summary). Parses both the verbose key/value dump and the short one-line identify output — and the source size feeds the resize hints and the info line under the command.
• Correct pipeline order. ImageMagick operators are sequential; settings like -filter, -gravity and -background only affect what follows. The builder emits every command in a working order: auto-orient → strip → resize → crop → rotate/flip → color/tone → effects → border → watermark → flatten → format settings → output.
• EXIF rationals handled. Camera values like FNumber: 28/10 and FocalLength: 69/10 are decoded to f/2.8 and 6.9 mm, exposure times to 1/250 s.
• Trim with fuzz. One checkbox crops away empty margins/background (-trim +repage), with a tolerance slider for the corner-pixel color (-fuzz) — because real-world backgrounds and JPEG artifacts are never perfectly uniform. Runs before resizing, so the result is sized after the trim.
• Print-ready DPI. Sets the output's resolution metadata (-units PixelsPerInch -density 300) for print workflows, and optionally rasterizes PDF/SVG inputs at that density — where -density must precede the input file to change the render resolution at all.
• ICC color profiles. Optional input/output profile fields emit -profile in the working order: the input profile is applied before any pixel operation (converting an embedded profile, or assigning one after -strip), the output profile converts the finished image last. With Strip active and no input profile, the tool warns that the output profile can only be assigned, not converted.
• GIF animation control. Frame delay, loop count and disposal method (-delay, -loop, -dispose — read-time settings placed before the input) plus Coalesce and Optimize frame operators, in a section that appears when the input or output is a GIF. Resizing an animation emits the working recipe: coalesce first, optimize last.
• Wrapped caption watermarks. The text watermark can switch from single-line -annotate to caption: with a wrap width — long copyright notes break into lines automatically and composite like an overlay image.
• Download as .bat / .sh. Two buttons save the current command as a ready-to-run script: a Windows .bat (CRLF lines, % doubled, pause at the end so error messages stay visible) and a .sh for macOS/Linux/WSL (paren escapes translated).
• Single file, fully offline, zero dependencies. One IMBlueprint.html — no Node build, no internet connection, nothing phoning home. Windows-aware (backslash paths, automatic quoting, cmd.exe paren escapes). Just open it, build, copy, run.

---

1. Getting started

1. Open IMBlueprint.html in your browser (double-click it, or drag it into a browser window).
2. Fill in the sections top to bottom. The Generated Command box at the bottom updates live as you change anything.
3. Click Copy on the command box, paste into a terminal, and run.

Note about the input path: browsers don't expose full file paths, so dropping a file or using the file picker only fills in the filename. The field flashes orange when that happens — type or paste the full path in front of it (e.g. C:\pictures\photo.jpg). Paths are quoted for you automatically.

Requirement: ImageMagick 7, so that the magick command is on your PATH. Check with magick -version. AVIF/HEIC output additionally needs a build with the libheif delegate (magick -list format shows which coders your build has). (Legacy ImageMagick 6 users: replace magick with the full path to convert, since Windows' own convert.exe would otherwise shadow it.)

2. Input & Output

• Input path / Output filename / Format — the format selector keeps the output extension in sync. PNG is the default because it is lossless and keeps transparency.
• Mode — Single image builds a magick command; Whole folder (mogrify) builds a magick mogrify command that writes all matches into the output folder. Run the batch command from the folder containing the images, or put the full path in the pattern (e.g. C:\pictures\*.jpg).
• Flatten transparency — composites any transparency onto the background color (-background … -alpha remove -alpha off). Needed for JPEG/BMP output; those formats enable it automatically.
• DPI (density) — sets the output resolution metadata for print (-units PixelsPerInch -density 300). With rasterize input at this density checked (default), a -density is also placed before the input file, where it controls the render resolution of PDF/SVG vector inputs.
• Analyze Image (optional) — copies a magick identify -verbose command; paste its output back to see the image's properties in a table and let the builder use the real source size in its hints.

3. Resize & Crop

• Resize modes: Off · Fit (aspect ratio, inside the box) · Long side (the longer edge — portrait or landscape — becomes the entered length; ideal for mixed folders, with an only shrink option so small images are not enlarged) · Stretch (exact size, distorts) · Cover (fills the box, crops the overflow from the center) · Percent.
• Trim empty margins — crops borders/uniform background away (-trim +repage), with a fuzz slider as tolerance for the corner-pixel color. Applied before resizing, so the trimmed content gets scaled.
• Size (W × H) — fill one side only to scale proportionally. With a known source size the hint line predicts the other side.
• Resize filter — auto (Lanczos) fits most photos; Mitchell is softer and good for upscaling; Point gives nearest-neighbor for pixel art.
• Crop — width/height are required, X/Y are the offsets, gravity decides where they start from (top-left by default, or center). +repage trims the virtual canvas afterwards and is on by default.

4. Rotate & Flip

• Auto-orient (EXIF) is on by default and should stay on for photos — it applies the camera's rotation flag before anything else.
• Rotate 90/180/270 or a custom angle; custom angles fill the gaps with the background color. Flip mirrors vertically, Flop mirrors horizontally.

5. Color & Tone

• Brightness / Contrast → -brightness-contrast BxC (−100…100 each).
• Saturation / Hue shift → -modulate (hue is converted from degrees to ImageMagick's 100-based scale for you).
• Gamma (emitted when ≠ 1.0), plus Grayscale, Invert, Sepia and Auto-level toggles.
• Color profiles (ICC) — optional input and output profile files emit -profile in the working order: the input profile is applied before any pixel operation (converting an embedded profile, or assigning one after -strip), and the output profile converts the finished image last. sRGB delivery for the web, or Adobe RGB for print, becomes a two-path affair instead of a guess.

6. Effects

• Blur (-blur 0xσ) and Sharpen (-sharpen 0xσ) use the sigma value directly — start around 1–2 and keep sharpening small.

7. Border & Watermark

• Border — pixel width/height plus color (-bordercolor … -border WxH).
• Watermark · Text — text, font size, fill and outline colors, gravity and offset; the text is quoted and inner quotes escaped automatically. The Text Method switch selects between single-line -annotate and caption: with a wrap width, which breaks longer text into lines automatically.
• Watermark · Image — a second image (PNG with transparency works best) placed by gravity + offset, with an opacity slider below 100 that fades it through its alpha channel. Available in single-image mode only — mogrify cannot composite.

8. Animation (GIF)

Shown when the input or output is a GIF. Frame delay and loop count are read-time settings and are placed before the input file, where ImageMagick applies them to every frame. Disposal method is emitted as -set dispose on the loaded frames — a pre-input -dispose is silently overwritten by the GIF reader with the disposal decoded from the file itself (verified against ImageMagick 7.1.2). Coalesce (-coalesce) expands all frames to full size — required before resizing an animation — and Optimize (-layers optimize) shrinks the result back down, emitted last. Together they form the canonical animation-resize recipe without hand-editing.

9. Quality & Metadata

• Quality — the slider follows the format: JPEG 92 (80–95 is the sweet spot), WebP 80 (with a lossless checkbox), AVIF 65, HEIC 85. PNG shows a compression level instead (lossless — only trades size vs. speed), TIFF a compression select.
• Strip metadata (-strip) removes EXIF/profiles — handy for privacy and size.
• Progressive / interlaced (-interlace Plane) for JPEG/PNG.

10. Extra

• Custom arguments — anything the UI doesn't cover is appended verbatim before the output, e.g. -define jpeg:dct-method=float or -coalesce for animated GIFs.

11. Generated Command

• Target Shell — Windows CMD, PowerShell or macOS/Linux. The displayed command and the Copy button always match this selection; on Mac/Linux machines the tool preselects bash. This matters as soon as a second image is involved: the image list parentheses need a different escaping per shell (^( ^) vs. "(" ")" vs. \( \)).
• The command updates live; Copy grabs it.
• Download .bat / .sh save it as a reusable script for frequent tasks — the .bat is built with cmd.exe escaping and % doubling, the .sh with bash escaping, regardless of the on-screen selection.
• Once Analyze Image has parsed a source image, the line under the command shows the source dimensions, format and filesize for reference.