Image Filename Patterns

## Why it matters

Bulk-saved images often arrive with opaque names: a3f9c2.jpg, asset_123.png, image-2024-001.webp. These sort randomly, collide if there's a second batch, and tell you nothing about the image without opening it. A filename pattern with just a few tokens gives them order, meaning, and findability.

If you download 50 product photos, naming them product-001.jpg, product-002.jpg, and so on means they sort correctly and you can spot a missing one at a glance. Add width and height (product-800x600-001.jpg) and you know which are desktop-sized without having to inspect each file. A subfolder like site-name-2024-07-19/ groups the batch and keeps your Downloads folder tidy.

## How it works

Before each download, Scalpel Images interpolates a pattern you've set. The tokens fill in with values from the image:

• {name}: the original filename from the URL, stripped of query strings and decoded. cdn.example.com/photo-abc123?size=large becomes photo-abc123.
• {ext}: the file extension, just the text part. jpg, png, webp, and so on.
• {index}: a sequence number. The first image is 001, the second is 002. This forces correct sorting past nine.
• {width}: the natural pixel width of the image file. Omitted if unknown.
• {height}: the natural pixel height of the image file. Omitted if unknown.
• {format}: the detected format. jpeg, png, webp, avif, gif, svg.
• {host}: the domain the image came from. cdn.example.com or images.site.co.uk. Useful if you're scraping multiple sources.
• {date}: today's date in YYYY-MM-DD format, so 2024-07-19.

Reserved filename characters (/, \, :, *, ?, ", <, >, |) are automatically stripped. If a token is empty (for example, an image with no width), the token simply vanishes from the name, leaving no gap. So photo-{width}x{height}.{ext} becomes photo.jpg if the size is unknown, not photo-x.jpg.

The pattern can also include an optional subfolder. Write downloads/{date}/ before the filename, and each batch lands in a dated folder. A slash anywhere tells Scalpel to create a folder; the filename part comes after the last slash.

If two images would save with the same name, the browser's conflictAction: "uniquify" kicks in and appends (1) or (2) to the filename, so nothing overwrites.

## What does not matter

You don't need to include every token. A pattern of just {index}.{ext} is fine if that's all you need. The simplicity often beats over-engineering.

Case sensitivity doesn't matter in the pattern itself, but the resulting filename will match what you typed. {name} and {Name} are the same token, but {name} or {Name} in your pattern just copies the original filename's case.

The {host} token is overkill for most jobs. If you're downloading from a single site, you won't need it. It's handy only if you're scraping multiple sources and want to know where each image came from without opening the folder.

EXIF data and metadata aren't part of the naming. The filename pattern works only on the URL and the image's dimensions and format, not on any metadata inside the file.

## Code example

Here are some practical patterns and what they produce:

// Pattern: {name}-{width}x{height}.{ext}
// Example image: https://cdn.example.com/hero.jpg (1920×1080)
// Result: hero-1920x1080.jpg

// Pattern: batch-{date}/{index}-{format}.{ext}
// First image (JPEG, 2024-07-19):
// Result: batch-2024-07-19/001-jpeg.jpg

// Pattern: {host}-{index}.{ext}
// Example: cdn.example.com + image 5
// Result: cdn.example.com-005.jpg

// Pattern: product/{name}.{ext}
// Example: https://shop.example.com/shoes-blue
// Result: product/shoes-blue.jpg

// Pattern: archive-{date}/{width}w/{name}.{ext}
// Example: 800px wide, 2024-07-19
// Result: archive-2024-07-19/800w/image-name.jpg
Copy

The {index} token always zero-pads to three digits by default. That keeps files sorted correctly: 001, 002, ..., 099, 100, etc. Without padding, 10 would sort between 1 and 2.

## How Scalpel shows it

The pattern input sits in the Scalpel Images footer, below the selection pane. Type a pattern, and a live preview shows you exactly what the first image will be named. The preview updates as you type, so you can experiment risk-free. If you make a typo, say, {wdth} instead of {width}, the preview shows the typo exactly as it would save, so you catch it before downloading 200 files with broken names.

Click the subfolder dropdown to toggle between saving flat to your Downloads folder or into a dated or custom subfolder. The "/" character stays in the subfolder field; everything after the last "/" is the filename pattern.