> For the complete documentation index, see [llms.txt](https://docs.viesus.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.viesus.com/support/faq.md).

# FAQ

Common questions about VIESUS, including interface-specific Q\&As. For step-by-step troubleshooting, see [Troubleshooting](/support/troubleshooting.md). For specific error codes, see [Error Codes](/support/error-codes.md).

***

## Getting started

<details>

<summary><strong>Can I use VIESUS in the cloud?</strong></summary>

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](https://www.viesus.cloud/) and start enhancing.

</details>

<details>

<summary><strong>What's the fastest way to try VIESUS?</strong></summary>

The [Cloud Quickstart](/get-started/quickstart-cloud.md) takes a few minutes — no install, no license. For on-premise, follow the [Image Enhancement Quickstart](/get-started/quickstart-image-enhancement.md) (or [PDF Enhancement Quickstart](/get-started/quickstart-pdf-enhancer.md) for PDFs). Both produce your first enhanced image in under 30 minutes.

</details>

<details>

<summary><strong>Which VIESUS interface should I use?</strong></summary>

Depends on your workflow. The [Choose Your Interface](/discover/choose-your-interface.md) decision guide compares the CLI, PDF Enhancer, Node.js module, C/C++ SDK, and Cloud API side by side.

</details>

***

## Licensing & pricing

<details>

<summary><strong>How is VIESUS priced?</strong></summary>

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.

</details>

<details>

<summary><strong>How do I create a license request file?</strong></summary>

In the [VIESUS Viewer](/tools/viesus-viewer.md), 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](/licensing/activation-key.md) for the full flow.

</details>

<details>

<summary><strong>How do I get a valid software key?</strong></summary>

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](/licensing/activation-key.md).

</details>

***

## Features

<details>

<summary><strong>What are Global Corrections?</strong></summary>

Global Corrections address overall image conditions — overexposure, underexposure, color casts. They affect the whole image uniformly. See [Global Color Correction](/features/features/global-color-correction.md).

</details>

<details>

<summary><strong>What are Local Corrections?</strong></summary>

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).

</details>

<details>

<summary><strong>What is AI Image Analysis?</strong></summary>

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.

See [Key Features → AI Image Analysis](/discover/key-features.md#ai-image-analysis).

</details>

<details>

<summary><strong>What is AI Upscaling?</strong></summary>

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.

See [Key Features → AI Upscaling](/discover/key-features.md#ai-upscaling).

</details>

<details>

<summary><strong>What is AI Facial Reconstruction?</strong></summary>

Restores faces from low-resolution images by filling in facial details that would otherwise be lost. Typically used alongside AI Upscaling for portraits.

</details>

<details>

<summary><strong>What is AI Artifacts Removal?</strong></summary>

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.

</details>

<details>

<summary><strong>How does VIESUS determine the correct skin tone?</strong></summary>

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.

</details>

<details>

<summary><strong>Which image formats are supported?</strong></summary>

VIESUS reads and writes common raster formats — JPEG, PNG, TIFF, and WebP — and extracts gainmaps from HDR HEIC/JPEG. See [Features → Image Formats](/features/image-formats.md) for the full list, HDR handling, and per-format notes.

</details>

<details>

<summary><strong>Is enhancement automatic, or can users opt in per image?</strong></summary>

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.

</details>

***

## Installation & versions

<details>

<summary><strong>Do I need a GPU?</strong></summary>

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](/installation/requirements.md).

</details>

<details>

<summary><strong>Do the AI features slow down processing?</strong></summary>

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](/operations/benchmarks.md).

</details>

<details>

<summary><strong>Can I migrate my existing INI/JSON config to a new VIESUS version?</strong></summary>

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.

</details>

<details>

<summary><strong>What should I do when installing a new VIESUS version?</strong></summary>

1. **Uninstall the old version first.** Don't install over the top.
2. **Restart your system** after both uninstall and install.
3. **Verify your license** before running production batches.

</details>

<details>

<summary><strong>Where do I see the latest VIESUS features?</strong></summary>

The product page: [viesus.com/how-it-works](https://www.viesus.com/how-it-works). For docs-side updates, check the [Changelog](/support/release-notes.md).

</details>

***

## Platform support

<details>

<summary><strong>Is there a VIESUS build for Alpine Linux?</strong></summary>

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.

</details>

<details>

<summary><strong>Which Windows versions does VIESUS support?</strong></summary>

Windows Server 2019, Windows Server 2022, Windows 10, Windows 11. Older Windows versions are not actively supported.

</details>

***

## Configuration

<details>

<summary><strong>What happens when my <code>viesusini.json</code> file is empty?</strong></summary>

VIESUS falls back to standard built-in defaults. The result is similar to the [Default preset](/configuration/presets-gallery.md) — basic enhancement without AI features.

</details>

<details>

<summary><strong>What's a sensible delay for hot folder processing?</strong></summary>

**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.

</details>

<details>

<summary><strong>What JPEG quality does VIESUS use for export?</strong></summary>

**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.

</details>

<details>

<summary><strong>How can I monitor enhancement results?</strong></summary>

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](/operations/monitoring.md).

</details>

***

## Integration

<details>

<summary><strong>How can I integrate VIESUS into my own server?</strong></summary>

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](/use-cases/nodejs-saas.md).
* **C/C++ SDK** — link the engine into your own application. See the [SDK overview](/reference/overview.md).

Use the [VIESUS Viewer](/tools/viesus-viewer.md) 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.

</details>

<details>

<summary><strong>Can I run VIESUS in Docker?</strong></summary>

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](/reference/docker/cli.md) and [Node.js → Docker](/reference/docker/nodejs.md).

</details>

<details>

<summary><strong>Is on-premise processing offline and private?</strong></summary>

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](/operations/security.md).

</details>

***

## Troubleshooting

<details>

<summary><strong>My GUID doesn't work — what should I check?</strong></summary>

1. Make sure the `viesus_64.dll` you're using is the one from the initial install — version mismatches break the GUID.
2. Verify the library version via the CLI (`viesus -v`). It should print something like `VIESUS X.XX.XX …`.
3. Confirm the GUID has no extra spaces or line breaks, and wrap it in quotes: `-g "your-guid-here"`.

</details>

<details>

<summary><strong>What does error code <code>-114</code> mean?</strong></summary>

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](/support/error-codes/cli.md).)

</details>

<details>

<summary><strong>Where else can I find help?</strong></summary>

* [Troubleshooting](/support/troubleshooting.md) — cross-product guide
* [Error Codes](/support/error-codes.md) — specific exit codes
* <info@viesus.com> — engineering support

</details>

***

## PDF Enhancer

<details>

<summary><strong>What types of PDFs does the PDF Enhancer support?</strong></summary>

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

</details>

<details>

<summary><strong>How is resizing handled in PDFs?</strong></summary>

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.

</details>

<details>

<summary><strong>What is the difference between hotfolder and stand-alone modes?</strong></summary>

| Mode            | When to use                                                                                                                                |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **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.                               |

</details>

<details>

<summary><strong>How do I check whether PDF processing was successful?</strong></summary>

Check the XML report file (`<filename>.pdf.xml`) in the output or status folder:

```xml
<error code="0" msg="no Failure"/>
```

Error code `0` = success. Any non-zero code indicates a failure. See [PDF Error Codes](/support/error-codes/pdf.md) for the full table.

</details>

<details>

<summary><strong>Can I process multiple PDFs in parallel?</strong></summary>

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.

</details>

<details>

<summary><strong>How much memory does the PDF Enhancer use?</strong></summary>

Memory usage depends heavily on the number and size of embedded images and the target output resolution. Rough estimates:

| Document type                         | Memory usage    |
| ------------------------------------- | --------------- |
| 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`.

</details>

<details>

<summary><strong>What is the TraceProducer?</strong></summary>

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.

</details>

<details>

<summary><strong>Why are some images in my PDF not being enhanced?</strong></summary>

VIESUS applies filtering to avoid processing non-photographic content. Check:

1. `minImageWidth` and `minImageHeight` in `settings.json` — images smaller than 64×64 px are skipped by default
2. `minFileSize` — images encoded as small streams may be below the threshold
3. `skipFullPageBackground` — full-page background images are skipped when this is enabled
4. `useColorRatio` — 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.

</details>

<details>

<summary><strong>How do I skip cover pages from PDF processing?</strong></summary>

Use the `-s` flag with stand-alone mode:

```bash
viesusPDF "photobook.pdf" "output/" "config.json" -s f,l
```

This skips the first (`f`) and last (`l`) pages. Add specific page numbers as needed: `-s f,l,5,10`.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.viesus.com/support/faq.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.