Local Image Upscaler

upscale, inspect, or compress jpg, png, or webp images locally on macos or windows. run upscayl's vulkan-based ncnn engine offline with automatic or manual profile selection (default, fast, photo, portrait, digital-art, sharp). output at 1k/2k/4k/8k or custom long edges. batch process folders. preserve aspect ratios. never overwrite source files. use this when the user asks to enlarge an image, enhance clarity, compare upscaling algorithms, inspect image resolution, or reduce file size to a target like 200kb.

inputs

image files

• path: jpg, png, or webp file or folder (local filesystem only)
• context: visual inspection to recommend profile (agent performs this)

runtime and models

• python 3.8+, bash or cmd (macos or windows x64)
• vulkan driver (check with vulkaninfo or vkcube; unavailable on some systems, stop and explain limitation if missing)
• disk space: runtime ~50-100 mb, each model 2.5-32 mb, temp processing space for 8k upscaling
• cache location: IMAGE_UPSCALER_CACHE env var (defaults to ~/.cache/upscaler)

external downloads (with fallback chain)

• primary: official upscayl/model mirrors
• secondary: configured mirrors via IMAGE_UPSCALER_MIRRORS env var (comma-separated url prefixes)
• tertiary: verified github acceleration endpoint
• fallback: official source
• all artifacts verified against pinned sha-256 digests (no bypass allowed)

optional configuration

• IMAGE_UPSCALER_MIRRORS: comma-separated url prefixes for domestic or org mirrors (prepended to official urls)
• IMAGE_UPSCALER_CACHE: override default cache directory
• --offline flag: forbid all network access (must have cached models)

procedure

step 1: inspect the input

• input: image file or folder path
• output: report dimensions, file size, aspect ratio, megapixels
• run: python scripts/inspect.py INPUT or python scripts/inspect.py INPUT_FOLDER --recursive --json
• edge case: if path does not exist, stop and ask for valid path
• edge case: if folder is empty, report and stop
• edge case: if file is corrupted or unreadable, stop and explain

step 2: visually inspect and recommend a profile

• input: the image itself (agent looks at it)
• output: one recommended profile with rationale, optionally with compact choice (advantage/disadvantage/download size) if the choice materially affects result
• decision: (see decision points section)
• edge case: if user does not choose, use default profile (balanced, conservative)
• note: do not block on profile selection; proceed with default if user is uncertain

step 3: prepare the runtime and selected model

• input: selected profile name
• output: cached runtime executable and model files, verified against sha-256
• run one of:
  • python scripts/setup.py --profile photo (or digital-art, sharp, etc.)
  • python scripts/setup.py --list-models (list choices without installing)
  • python scripts/setup.py --model high-fidelity (prepare all models for high-fidelity mode)
• flags:
  • --offline: forbid network access (requires cache already populated)
  • --platform windows-x64 --download-only: prefetch windows files on another machine
• edge case: if vulkan is unavailable, stop immediately and explain platform limitation; do not fall back to cloud service
• edge case: if disk space is insufficient, report required space and stop
• edge case: if download fails after all fallback sources, explain the network or mirror issue and suggest retry or offline mode
• edge case: if sha-256 verification fails, reject the artifact and retry; never bypass verification

step 4: upscale or compress

• input: image file or folder, target dimensions or file size, output path, optional profile and format
• output: upscaled or compressed file(s) at output path

upscale variant:

• run: python scripts/upscale.py INPUT --output OUTPUT.png --target 4k (or other target/profile/format)
• common targets: 1k (1920px long edge), 2k (2560px), 4k (3840px), 8k (7680px), scale4 (native 4x), --max-edge N (custom)
• common profiles: default, fast, photo, portrait, digital-art, sharp
• common formats: png (lossless, larger), jpg (lossy, smaller, no transparency, supply --compression 92 for quality)
• flags:
  • --tile 256 or --tile 128: for 8k or gpu memory errors, reduce tile size and retry
  • --target scale4 --format webp: webp support with native output size only
• edge case: if output dimensions request 8k beyond native 4x result, high-quality resizing applies; do not claim invented texture is recovered detail
• edge case: if 8k uses high memory, start with --tile 256; if it fails, reduce to --tile 128
• edge case: if gpu memory exhausted, explain tiling requirement and retry with smaller tile size
• batch: python scripts/upscale.py INPUT_FOLDER --output OUTPUT_FOLDER --target 4k (processes all images in folder)

compress variant:

• run: python scripts/compress.py INPUT --output OUTPUT.jpg --target-kb 200 (or --target-mb 1.5)
• flags:
  • --keep-dimensions: forbid resolution reduction (quality only)
  • --min-edge 640: minimum long edge when resolution reduction is used (default 640px)
  • --recursive: process subfolders in batch
  • --dry-run: preview changes without writing
  • --overwrite: replace existing output files (default appends -v2, -v3, etc.)
• algorithm: first reduce jpeg quality; if insufficient, reduce dimensions proportionally while respecting --min-edge
• edge case: if target is unachievable with --keep-dimensions, report the smallest possible size and ask for larger target
• edge case: if input is transparent png, warn that jpeg conversion requires explicit background color before compression
• edge case: on batch processing, use --dry-run first for large folders

step 5: verify output

• input: output file(s) from step 4
• output: confirmation report with profile used, output path, dimensions, file size, aspect ratio preserved
• check: file exists, dimensions match request (or are closest possible), source aspect ratio preserved
• check: output is never the same as input path (source never overwritten)
• edge case: if dimensions do not match (e.g., tiling artifact), report discrepancy and suggest retry with different tile size or profile

decision points

profile selection:

• if user inspects a clean ai-generated portrait or professional studio headshot, recommend default (balanced, conservative)
• if user inspects a noisy, compressed, or rough natural portrait, recommend portrait (smoother rendering, removes fine skin texture detail)
• if user inspects a photograph with mixed content or uncertain subject, recommend default
• if user inspects photographic content with natural texture, recommend photo (natural texture, less crisp on text/architecture)
• if user inspects anime, illustration, or vector-like art, recommend digital-art (clean edges, may oversimplify photo texture)
• if user inspects content that needs maximum apparent edge sharpness (documents, architecture, technical drawings), recommend sharp (strongest edge detail, may exaggerate noise/halos/artifacts)
• if user inspects extremely noisy or low-res content and speed matters, recommend fast (smallest model, weakest fine-detail, ~2.5 mb download)
• if user does not state a preference after recommendation, use default (do not block)

format selection:

• if user requests maximum upscale quality, use png (lossless)
• if user requests strict file-size target, use jpg with quality parameter (lossy, smaller)
• if user needs transparency in output, use png (jpeg does not support alpha)
• if user specifies webp, only support with --target scale4 (native 4x output size)

compression strategy:

• if user specifies target file size and dimensions are flexible, compress with quality reduction then proportional dimension reduction
• if user specifies target file size and --keep-dimensions is set, reduce quality only; if insufficient, report smallest achievable size
• if user specifies target file size and input is transparent png, warn that jpeg conversion requires explicit background color

runtime and cache:

• if selected profile model is not cached, explain download size and disk cost, then run setup
• if --offline is set and model is not cached, stop and explain that model must be prefetched
• if setup fails after all fallback sources, suggest user check network, configure mirrors, or prefetch on another machine

network and mirrors:

• if download fails from primary source, automatically try secondary mirrors (IMAGE_UPSCALER_MIRRORS), then github, then official source
• if all sources fail and --offline is not set, explain the network issue and suggest retry or --offline mode (if cache exists)
• if sha-256 verification fails at any point, reject the artifact and stop (do not bypass or retry with unverified file)

output contract

upscale output:

• file location: user-specified output path (e.g., OUTPUT.png)
• format: png or jpg based on request
• dimensions: long edge matches target (1920, 2560, 3840, 7680, or custom), source aspect ratio preserved
• file size: png is larger (lossless); jpg depends on quality parameter
• metadata: original dimensions, final dimensions, profile used, aspect ratio preserved (y/n)

compress output:

• file location: user-specified output path (e.g., OUTPUT.jpg)
• file size: ≤ target (e.g., 200 kb)
• dimensions: original unless resolution reduction was needed; never stretched or upscaled
• aspect ratio: preserved
• metadata: original size, final size, quality reduction applied, dimension reduction applied (y/n)

inspect output:

• dimensions (wxh in pixels)
• simplified aspect ratio (16:9, 4:3, 1:1, custom)
• megapixels
• file size
• optional json format for automation

batch output:

• all files in input folder processed to output folder, same naming convention
• each file report logged or summarized
• on error, stop batch and report which file failed

outcome signal

• upscale: user confirms output image is larger, clearer, or sharper than input; dimensions match request; source aspect ratio is intact; source file is unchanged
• compress: user confirms output file is smaller than target; dimensions are as expected; image quality is acceptable; source file is unchanged
• inspect: user receives report with dimensions, aspect ratio, and file size; can then decide on upscale or compression strategy
• batch: user receives summary of all processed files; can verify output folder contains expected files with correct dimensions
• error cases: user sees explicit stop message (vulkan unavailable, disk space insufficient, download failed, sha-256 mismatch, network timeout); user does not encounter silent fallback to unrelated service or unverified downloads