FAQ
Answers to the most common questions about VIESUS — interfaces, licensing, features, configuration, integration, and troubleshooting.
Common questions about VIESUS, including interface-specific Q&As. For step-by-step troubleshooting, see Troubleshooting. For specific error codes, see Error Codes.
Getting started
Can I use VIESUS in the cloud?
Yes. The VIESUS Cloud runs the same enhancement engine on dedicated Viesus AG infrastructure, exposed via GraphQL API and a browser-based Cloud App. No install required — sign up at viesus.cloud and start enhancing.
What's the fastest way to try VIESUS?
The Cloud Quickstart takes a few minutes — no install, no license. For on-premise, follow the Image Enhancement Quickstart (or PDF Enhancement Quickstart for PDFs). Both produce your first enhanced image in under 30 minutes.
Which VIESUS interface should I use?
Depends on your workflow. The Choose Your Interface decision guide compares the CLI, PDF Enhancer, Node.js module, C/C++ SDK, and Cloud API side by side.
Licensing & pricing
How is VIESUS priced?
Pricing depends on three factors:
Solution type — on-premise vs Cloud
Feature set — traditional enhancement vs AI features
Volume — images processed per month/year
Contact info@viesus.com for a quote tailored to your volume and workflow.
How do I create a license request file?
In the VIESUS Viewer, choose Help → Create License Request from the toolbar. The request file goes to Viesus AG; you receive your license key file back by email. See Licensing → Activation Key for the full flow.
How do I get a valid software key?
Software keys (Activation Keys) are issued by Viesus AG after purchase and are bound to your machine's hardware. If hardware changes you may need to renew. For the full step-by-step request and renewal flow, see Licensing → Activation Key.
Features
What are Global Corrections?
Global Corrections address overall image conditions — overexposure, underexposure, color casts. They affect the whole image uniformly. See Global Color Correction.
What are Local Corrections?
Local Corrections affect only the parts of the image that need them. Informed by AI Image Analysis, they include targeted correction of shadows and highlights, skin tones, per-zone color, sharpness, red-eye, and the brightness of faces (Adaptive Face Flash).
What is AI Image Analysis?
The first step in the VIESUS pipeline. It detects the image's composition — content (people, skin tones, sky, vegetation), setting (indoor, outdoor, back-lit), and technical conditions (noise, focus, exposure). The result informs every subsequent enhancement step.
What is AI Upscaling?
AI Upscaling increases image size and printable resolution by "inventing" new pixels — up to 16× the source. Unlike traditional upscaling, it recovers fine detail. Frequently paired with AI Artifacts Removal and AI Facial Reconstruction.
What is AI Facial Reconstruction?
Restores faces from low-resolution images by filling in facial details that would otherwise be lost. Typically used alongside AI Upscaling for portraits.
What is AI Artifacts Removal?
Removes JPEG compression artifacts and other render errors — pixelation, blocking, halos — to recover smooth gradients and clean edges. Often used as a pre-step before AI Upscaling so the model isn't amplifying compression noise.
How does VIESUS determine the correct skin tone?
VIESUS uses extensive research across 40,000+ portrait images to model an "ideal" skin tone for every skin color. The correction is proportional to the deviation between the detected skin tone and that ideal — and stays subtle to avoid artificial results. The focus is on natural enhancement, not standardisation.
Which image formats are supported?
VIESUS reads and writes common raster formats — JPEG, PNG, TIFF, and WebP — and extracts gainmaps from HDR HEIC/JPEG. See Features → Image Formats for the full list, HDR handling, and per-format notes.
Is enhancement automatic, or can users opt in per image?
VIESUS itself is fully automatic. Whether your end users see an opt-in choice depends on how you integrate VIESUS in your workflow. Generally, VIESUS enhances poor images more and good images less — so applying it by default rarely degrades anything.
Installation & versions
Do I need a GPU?
Only for the AI features. AI Upscaling, AI Artifacts Removal, AI Facial Reconstruction, and AI Background Handling require an NVIDIA GPU (Ampere or newer, ≥ 8 GB VRAM, CUDA 12.6 or later). Traditional enhancement — color, contrast, sharpening, noise reduction, red-eye, and classical resizing — runs CPU-only. See System Requirements.
Do the AI features slow down processing?
Per image, AI algorithms add initial model-load time over traditional processing — you'll notice it on a single image in the Viewer. In a batch, the model-load cost amortises across many images and per-image throughput is comparable. Newer CPUs and GPUs narrow the gap further. See Benchmarks.
Can I migrate my existing INI/JSON config to a new VIESUS version?
Yes — the config file is self-contained and upward-compatible with newer versions. To pick up newly added parameters, load the file in the latest VIESUS Viewer and save it again. The Viewer adds any missing fields with default values.
What should I do when installing a new VIESUS version?
Uninstall the old version first. Don't install over the top.
Restart your system after both uninstall and install.
Verify your license before running production batches.
Where do I see the latest VIESUS features?
The product page: viesus.com/how-it-works. For docs-side updates, check the Changelog.
Platform support
Is there a VIESUS build for Alpine Linux?
Not currently. Standard Linux distributions (Debian, Ubuntu, RHEL, Rocky) are supported via the official .deb package and an LSB-compatible binary. Get in touch if Alpine is a hard requirement for your deployment.
Which Windows versions does VIESUS support?
Windows Server 2019, Windows Server 2022, Windows 10, Windows 11. Older Windows versions are not actively supported.
Configuration
What happens when my viesusini.json file is empty?
VIESUS falls back to standard built-in defaults. The result is similar to the Default preset — basic enhancement without AI features.
What's a sensible delay for hot folder processing?
60 seconds is the usual recommendation. The delay is measured in seconds from the last file modification — a file is picked up on the next scan once it's older than the delay and can be opened exclusively for reading. This prevents partial-file ingestion when an upstream process is still writing.
What JPEG quality does VIESUS use for export?
95. This is a proven quality level for printing and produces measurably smaller files than 100 thanks to JPEG's compression curve, without visible quality loss.
How can I monitor enhancement results?
VIESUS is designed to run unmonitored, but you can add output-folder taps to your workflow — copy a small percentage of enhanced images to a review folder for spot checks. The Folder Enhancer and CLI both support this pattern. See Operations → Monitoring.
Integration
How can I integrate VIESUS into my own server?
Several options depending on your stack:
Folder Enhancer — drop-in hot folder solution for Windows. Configure one or more watched folders; processed files appear in matching output folders.
CLI — for Windows and Linux. Call from any pipeline or scheduler that can invoke a binary.
Node.js module — embed enhancement directly in a Linux Node.js service (worker-pool pattern). See the Node.js SaaS use case.
C/C++ SDK — link the engine into your own application. See the SDK overview.
Use the VIESUS Viewer to define your enhancement parameters interactively and export the JSON for your production pipeline. For PDFs, the PDF Enhancer is a separate product with its own license.
Can I run VIESUS in Docker?
Yes. The CLI and the Node.js module both run in containers; GPU features need the NVIDIA Container Toolkit and --gpus all. See CLI → Docker and Node.js → Docker.
Is on-premise processing offline and private?
Yes. On-premise VIESUS makes no outbound network connections for licensing — GUID licenses are passed at runtime and Activation Keys are activated offline — so the service can run fully air-gapped and your images never leave your infrastructure. (VIESUS Cloud, by contrast, processes on Viesus AG infrastructure.) See Operations → Security.
Troubleshooting
My GUID doesn't work — what should I check?
Make sure the
viesus_64.dllyou're using is the one from the initial install — version mismatches break the GUID.Verify the library version via the CLI (
viesus -v). It should print something likeVIESUS X.XX.XX ….Confirm the GUID has no extra spaces or line breaks, and wrap it in quotes:
-g "your-guid-here".
What does error code -114 mean?
The files have already been processed and can't be enhanced again. Pass -a to force re-enhancement, or restore the source from your archive and change the output target/filename. (-114 is library error -14 — see CLI Exit Codes.)
Where else can I find help?
Troubleshooting — cross-product guide
Error Codes — specific exit codes
info@viesus.com — engineering support
PDF Enhancer
What types of PDFs does the PDF Enhancer support?
PDFs with embedded raster images — typical output from layout applications like InDesign, QuarkXPress, and similar tools producing unflattened PDFs for photobooks, catalogs, and print products.
Not supported / limited support:
Password-protected PDFs
Fully rasterized/flattened PDFs (nothing to enhance — the entire content is already pixels)
PDFs with only vector artwork and no embedded raster images
How is resizing handled in PDFs?
Images in a PDF are attached as a stream to a containing rectangle. The rectangle's size is defined in points (1/72 inch). At the target print resolution (e.g. 300 DPI), that rectangle maps to a pixel area. If the image stream doesn't contain enough pixels to fill the container at the target resolution, upscaling is required.
The PDF Enhancer can perform this upscaling during processing — using classical algorithms or AI upscaling — ensuring the output PDF contains sufficient pixel data for the target print DPI.
What is the difference between hotfolder and stand-alone modes?
Hotfolder
Automated print workflows where PDFs are deposited by upstream systems. The PDF Enhancer runs continuously and monitors the source folder.
Stand-alone
Scripted processing of specific files, one-off enhancement, or testing. Run from the command line on demand.
How do I check whether PDF processing was successful?
Check the XML report file (<filename>.pdf.xml) in the output or status folder:
Error code 0 = success. Any non-zero code indicates a failure. See PDF Error Codes for the full table.
Can I process multiple PDFs in parallel?
Yes. Run multiple instances of viesusPDF simultaneously. For CPU-only processing, scale to the number of available cores. For GPU processing, limit parallel instances to the number of available GPUs — running more instances than GPUs doesn't increase throughput.
How much memory does the PDF Enhancer use?
Memory usage depends heavily on the number and size of embedded images and the target output resolution. Rough estimates:
Small PDF (1–5 images)
100 MB – 1 GB
Medium PDF (5–20 images)
500 MB – 4 GB
Large PDF (20+ images)
2 GB – 8 GB+
High-resolution processing (600+ DPI)
May exceed 8 GB
If you hit OOM errors, reduce maxFactor and maxTargetSize in settings.json.
What is the TraceProducer?
The TraceProducer is a Windows desktop application that collects real-time trace, warning, and error messages from the PDF Enhancer over a network connection. It's useful for diagnosing processing failures that don't produce clear error codes in the XML.
The TraceProducer runs on Windows but can collect traces from PDF Enhancer instances running on both Windows and Linux over TCP.
Why are some images in my PDF not being enhanced?
VIESUS applies filtering to avoid processing non-photographic content. Check:
minImageWidthandminImageHeightinsettings.json— images smaller than 64×64 px are skipped by defaultminFileSize— images encoded as small streams may be below the thresholdskipFullPageBackground— full-page background images are skipped when this is enableduseColorRatio— if enabled, images with low color variation (e.g. gradients) may be filtered
Run with justAnalyze first to see the total image count the PDF Enhancer detects.
Last updated
Was this helpful?