# Welcome VIESUS delivers state-of-the-art quality on every image, scales with your production volume without becoming a bottleneck, and ensures results stay natural and consistent.

VIESUS enhancement: before and after — Click image to view original size. Artifact removal and 2× AI upscaling.

Running in the background of automated production, [VIESUS](https://viesus.com) is used by leading photo labs, print services, and digital media platforms worldwide — enhancing tens of millions of images per day, fully automatically. ## Get instant help Ask questions in plain language, right here. You get tailored answers based on this documentation. *** ## New here? The fastest way to try VIESUS is [**VIESUS Cloud**](/get-started/quickstart-cloud) — no installation and no license required. Sign up and enhance your first image in minutes. For an **on-premise** evaluation or deployment, these five steps walk you all the way to your first enhanced image — including the option to request a **trial license** before purchasing. {% stepper %} {% step %} #### Understand the product Read [What is VIESUS?](/discover/what-is-viesus) for a plain-language overview of what the engine does and how it's deployed. {% endstep %} {% step %} #### Check system requirements Review [System Requirements](/installation/requirements) for hardware, OS, and GPU requirements per interface. {% endstep %} {% step %} #### Get a license Contact to request a **trial license** (try VIESUS before purchase) or to license directly. See [Get a License](/get-started/get-a-license) for what to expect. {% endstep %} {% step %} #### Pick your interface Use the [Choose Your Interface](/discover/choose-your-interface) decision guide to select CLI, PDF Enhancer, Node.js module, SDK, or Cloud. {% endstep %} {% step %} #### Enhance your first image Follow the [Image Enhancement Quickstart](/get-started/quickstart-image-enhancement) for your first on-premise image run, or the [PDF Enhancement Quickstart](/get-started/quickstart-pdf-enhancer) for PDFs. {% endstep %} {% endstepper %} Once you've enhanced your first image, explore the [Use Cases](/use-cases/photo-lab-batch) for end-to-end production patterns or dive into the [Parameter Reference](/configuration/parameter-reference) to tune your configuration. To try ready-made configurations, browse the [Presets Gallery](/configuration/presets-gallery) and start with the preset that best fits your workflow. # What is VIESUS? A plain-language overview of the VIESUS image enhancement engine — what it is, who uses it, how it works, and what makes it different. VIESUS™ is a professional automatic image enhancement engine. It analyses each image individually and applies the optimal combination of color correction, contrast, brightness, sharpening, noise reduction, repair, and AI upscaling — fully automatically, without human review. Unlike desktop tools built for retouching images one at a time, VIESUS runs in the background of automated production, improving millions of images a day without manual steps or interrupting the workflow. It is built for real-world input. Low-resolution or messenger-compressed customer photos that would otherwise show visible quality loss in print are prepared automatically. The same engine powers photo lab production lines, ID photo systems, SaaS image platforms and many other workflows worldwide. ## Who uses VIESUS


Photo labs & print services	Enhance millions of customer images for paper prints, photobooks, canvas, mugs, and calendars.
Digital media & SaaS platforms	Optimise user-uploaded images automatically before display, download, or fulfilment. Integrate through the Cloud API or Node.js module.
Industrial printing	Keep image quality consistent across mixed source files in catalogue, marketing, and packaging production.
Event & school photography	Apply face-aware enhancement, auto-cropping, and background handling for school, event, and similar portrait workflows.

## How VIESUS works {% stepper %} {% step %} #### Analyse VIESUS analyses every image and detects [faces](/features/features/face-detection), skin tones, sky, vegetation, noise patterns, focus quality, and dozens of other characteristics. Results feed every subsequent step. {% endstep %} {% step %} #### Enhance Per-image [color correction](/features/features/global-color-correction), contrast, brightness, [sharpening](/features/features/sharpening), and skin-tone adjustments are applied locally (where they help) and globally (where appropriate). [vScene](/features/scene-based-enhancement) tailors the parameters to the detected scene type. {% endstep %} {% step %} #### Repair (optional) [JPEG compression artifacts](/features/features/ai-artifact-removal) are removed. [Noise](/features/features/noise-reduction) is reduced. [Red-eye](/features/features/red-eye-removal) is corrected. [AI Upscaling](/features/features/ai-super-resolution) and [AI Facial Reconstruction](/features/features/face-reconstruction) can bring low-resolution sources up to print-grade quality. {% endstep %} {% step %} #### Output The enhanced image is written to the target format (JPEG, TIFF, PNG, or PDF), preserving the source's natural character. No manual review needed. {% endstep %} {% endstepper %} ## Where it runs VIESUS ships as both an **on-premise** library and a hosted **cloud API**. On-premise interfaces (CLI, PDF Enhancer, Node.js module, C/C++ SDK) all wrap the same C++ engine and share a single `viesusini.json` configuration. The VIESUS Cloud exposes the same enhancement engine over a GraphQL API for integrations that prefer not to manage their own infrastructure. Cloud is the easiest way to **try** VIESUS; for production volume we generally recommend **on-premise**, which runs locally and is faster and more cost-efficient at scale — see [Cloud vs on-premise](/discover/choose-your-interface#cloud-vs-on-premise) for the trade-off and a break-even example. # Key Features VIESUS combines traditional image enhancement with AI-powered features for analysis, optimization, repair, upscaling, and composition. VIESUS offers automatic, per-image enhancement across the capability areas below. Every feature is controlled by parameters in `viesusini.json` and works identically across all on-premise interfaces.


Image Quality	Per-image color, contrast, sharpening, noise reduction, face detection, and red-eye removal — the main enhancement catalogue.	placeholder.svg	Image Quality
HDR Support	Tonemap HDR images (HEIC, JPEG with gainmap) to SDR with seven tonemapping modes.	placeholder.svg	HDR Support
Native PDF Enhancement	Process PDFs with embedded images — enhance each image while preserving layout, fonts, and vectors.	placeholder.svg	Native PDF Enhancement
Image Formats	Supported input and output formats — JPEG, TIFF, PNG, HEIC, WebP, and more.	placeholder.svg	Image Formats
AI Upscaling	Increase printable resolution up to 16× — AI super-resolution invents detail that traditional interpolation can't recover.	placeholder.svg	Image Quality
Background Handling	AI segmentation to remove, replace, blur, or composite the background of portraits and product shots.	placeholder.svg	Image Quality

For ready-to-use starting configurations, see the [Presets Gallery](/configuration/presets-gallery). For the parameter-level technical reference, see the [Parameter Reference](/configuration/parameter-reference). # Choose Your Interface A decision guide for picking the right VIESUS interface — CLI, PDF Enhancer, Node.js module, C/C++ SDK, or Cloud API. All VIESUS interfaces wrap the same enhancement engine and produce identical output for the same input and settings. The right choice depends on where your workflow runs, what you're processing, and how much infrastructure you want to manage. {% hint style="success" %} **Try on Cloud, run production on-premise.** VIESUS Cloud is the fastest way to evaluate enhancement quality. Once you're happy with the results, on-premise is our recommendation for production — it runs locally, which is faster and more cost-efficient at scale. See [Cloud vs on-premise](#cloud-vs-on-premise) below. {% endhint %} *** ## Quick decision


VIESUS Cloud	No server infrastructure, pay per image. Also the easiest way to try AI upscaling without a local NVIDIA GPU.	placeholder.svg	Overview
VIESUS CLI	Batch-process images from the command line or a shell script.	placeholder.svg	CLI Reference
VIESUS PDF Enhancer	Process PDF documents with embedded images — photobooks, catalogues, marketing print.	placeholder.svg	PDF CLI
VIESUS Node.js Module	Integrate enhancement into a Node.js web server or cloud pipeline (Linux only).	placeholder.svg	Overview
VIESUS C/C++ SDK	Embed enhancement inside a C/C++ application without a subprocess call.	placeholder.svg	C/C++ SDK
Desktop Tools	Windows GUI apps — tune enhancement settings interactively with the VIESUS Viewer, or run automated hotfolder pipelines with the Folder Enhancer.	placeholder.svg	VIESUS Viewer

*** ## Cloud vs on-premise Every interface produces the same enhancement, so the real decision is **where it runs**. VIESUS Cloud is the easiest way to **try** enhancement — no install, no GPU, and a free tier to evaluate. Once you're satisfied with the quality, we recommend running **on-premise for production**: it runs locally, which is roughly **twice as fast** and — since you're not paying for hosted infrastructure on every image — **steadily cheaper the more you process**. How the costs compare depends on whether you need AI upscaling and at what volume:

Option	Up-front cost	Per AI-upscaled image	Break-even
VIESUS Cloud	None	~CHF 0.06 (4 credits; CHF 75 = 5,000 credits)	—
On-premise — no AI upscaling	None	—	Immediately
On-premise — GPU upgrade (RTX 4000 Ada)	~CHF 1,500	None	~25,000 images
On-premise — dedicated system (NVIDIA DGX Spark)	~CHF 4,000	None	~70,000 images

*Indicative figures, as of 06/2026. Without AI upscaling, on-premise has no per-image cost and needs no special hardware, so it's cheaper than Cloud from the first image. With AI upscaling, past the break-even on-premise keeps getting cheaper while Cloud keeps charging per image — adding a GPU to an existing workstation is the lowest-cost entry; a dedicated system suits higher sustained volume.* **Rule of thumb:** evaluate on Cloud, run high volume on-premise. *** ## Detailed comparison

VIESUS CLI

**Best for:** Automated batch processing of image files on Windows or Linux servers. The `viesus` command-line tool reads a list of image paths (or individual files), applies enhancement, and writes output to a configurable destination. It is designed to be called from shell scripts, cron jobs, or orchestration tools. ```bash viesus -l images.lst -s -p config.json ``` **Strengths:** * Simple to integrate into any pipeline — no programming required * Scales by running multiple instances in parallel * Works on Windows and Linux (x64, arm64) * Supports Docker **Limitations:** * File-based I/O only — images must be written to disk before and after processing → [VIESUS CLI documentation](/reference/cli-reference)

VIESUS PDF Enhancer

**Best for:** Processing PDFs with embedded images — photobooks, marketing print, catalogs. The `viesusPDF` tool opens a PDF, locates embedded images, enhances each one, and writes a new PDF with the improved images. It supports hotfolder monitoring mode (watches a folder for new PDFs) and standalone mode (processes a specific file or folder). ```bash viesusPDF input.pdf output/ config.json ``` **Strengths:** * Operates directly on PDFs without pre-extracting images * Hotfolder mode for fully automated print workflows * Generates XML processing reports per PDF **Limitations:** * Processes images embedded in PDFs; not suitable for standalone image files * Not available as a Node.js module → [VIESUS PDF Enhancer documentation](/reference/pdf-cli)

VIESUS Node.js Module

**Best for:** JavaScript-based web servers, REST APIs, SaaS platforms where enhancement happens on upload. The Node.js module is a native C++ addon that calls the VIESUS library in-process from Node.js. It uses a worker thread pool so enhancement runs off the main event loop without blocking. ```js const viesusObj = new viesus.MyViesusObject(guid); const result = viesusObj.Enhance(fromPath, toPath, iniPath, resPath); ``` **Strengths:** * In-process — no subprocess overhead * Worker thread pool keeps the event loop unblocked * Scales to multiple CPUs or GPUs by adjusting pool size **Limitations:** * Linux only (Ubuntu 22.04+) * Requires CUDA 12.6 driver for GPU features → [VIESUS Node.js Module documentation](/reference/node.js-module/overview)

VIESUS C/C++ SDK

**Best for:** Existing C or C++ applications that need enhancement as a function call, not an external process. The SDK exposes a C API via `IsEnhance.h`. Link against the VIESUS shared library and call enhancement directly from your code. Any language with a C FFI can wrap it. **Strengths:** * No subprocess; minimal latency * Access to per-image analysis data (detected faces, scene type, correction strengths) * Any language with C FFI bindings can use it **Limitations:** * Requires C/C++ integration effort * Access requires contacting Viesus AG → [VIESUS C/C++ SDK documentation](/reference/overview)

VIESUS Cloud

**Best for:** No-infrastructure integrations, testing AI upscaling, or pay-per-image billing. VIESUS Cloud is a GraphQL API hosted by Viesus AG. Upload an image or PDF, trigger enhancement, and download the result. No library installation, no GUID, no server to manage. ```bash curl -X POST https://api.viesus.cloud/graphql \ -H "x-api-key: your-key" \ -d '{"query": "mutation { ... }"}' ``` **Strengths:** * No hardware or software setup * Free tier with 200 credits to evaluate (no credit card required) * AI upscaling without needing a local NVIDIA GPU * Credit-based billing — pay only for what you process **Limitations:** * Requires internet access and file upload * Not suitable for air-gapped environments * Processing is subject to API rate limits and server availability → [VIESUS Cloud documentation](/reference/cloud-api/overview)

*** ## Platform support matrix | Interface | Windows x64 | Linux x64 | Linux arm64 | macOS | | -------------- | :---------: | :--------: | :---------: | :--------: | | CLI | ✓ | ✓ | ✓ | — | | PDF Enhancer | ✓ | ✓ | ✓ | — | | Node.js Module | — | ✓ | ✓ | — | | C/C++ SDK | ✓ | ✓ | ✓ | — | | Cloud API | ✓ (client) | ✓ (client) | ✓ (client) | ✓ (client) | # Image Quality Every VIESUS enhancement feature — automatic color, sharpening, face reconstruction, AI upscaling, background handling, and more. All features below apply to every VIESUS on-premise interface (CLI, PDF Enhancer, Node.js module, C/C++ SDK) and are controlled through the shared `viesusini.json` configuration file. For exact parameter values, ranges, and mode tables, click on feature to see the corresponding parameters or see the [Parameter Reference](/configuration/parameter-reference). ***


Base Enhancement	Automatic per-image color, brightness, and contrast correction scaled to each image.	placeholder.svg	Base Enhancement
Global Color Correction	Remove color casts and restore natural, balanced tones.	placeholder.svg	Global Color Correction
Shadow & Highlight Recovery	Recover detail in shadow and highlight regions.	placeholder.svg	Shadow & Highlight Recovery
Noise Reduction	Reduce color and luminance grain — automatic profiling or AI denoising.	placeholder.svg	Noise Reduction
Sharpening	Local sharpening for textured detail; optional AI deblur for slightly out-of-focus shots.	placeholder.svg	Sharpening
Face Detection	Detect faces and enable targeted portrait enhancements like red-eye and face reconstruction.	placeholder.svg	Face Detection
Face Reconstruction	AI reconstruction of small or compressed facial detail.	placeholder.svg	Face Reconstruction
Red-Eye Removal	Detect and remove flash red-eye artifacts.	placeholder.svg	Red-Eye Removal
AI Artifact Removal	AI removal of JPEG compression artifacts, blocking, and ringing.	placeholder.svg	AI Artifact Removal
AI Super Resolution	Deep-learning upscaling up to 16× — invents detail beyond traditional interpolation.	placeholder.svg	AI Upscaling
Background Handling	AI segmentation — remove, replace, or composite portraits and product shots.	placeholder.svg	Background Handling
Background Blur	Computational bokeh — blur the background while keeping the subject sharp.	placeholder.svg	Background Blur
Grain Addition	Add subtle film grain to reduce banding in smooth gradient areas.	placeholder.svg	Grain Addition
Local Color Correction	Fine-tune skin, sky, and vegetation zones independently.	placeholder.svg	Local Color Correction
Skin Tone Enhancement	Keep skin tones natural and fine-tune the skin color zone.	placeholder.svg	Skin Tone Enhancement
Scene-Based Enhancement	Scene-aware tuning — portrait, landscape, night, beach, snow, sunset, and more.	placeholder.svg	Scene-Based Enhancement
HDR Tonemapping	Extract gainmaps from HDR HEIC/JPEG and tonemap to SDR with seven methods.	placeholder.svg	HDR Support
Portrait Auto Cropping	Auto-crop portraits based on face position and configurable aspect ratio.	placeholder.svg	Portrait Auto Cropping
White Fix	Remove print-related grey speckling in light and white areas.	placeholder.svg	White Fix
Adaptive Face Flash	Subtle fill-flash for underlit or backlit faces.	placeholder.svg	Adaptive Face Flash
ICC Color Management	Control the ICC color profile assigned to output images.	placeholder.svg	ICC Color Management
Monochrome & Sepia	Convert output to black-and-white or toned monochrome (sepia).	placeholder.svg	Monochrome & Sepia

# Base Enhancement Automatic image quality correction. Analyses each image and applies brightness, contrast, and color correction scaled to the individual image's needs. ## Example {% columns %} {% column %} **Before**

Before — Base Enhancement — Original JPEG out of Camera

{% endcolumn %} {% column %} **After**

After — Base Enhancement — Enhanced by VIESUS with vScene activated

{% endcolumn %} {% endcolumns %} ## Parameters

Parameter	Section	Value	Default	Description
`Enhancemode`	`Config`	0 – 3	1	Enhancement mode (see below)
`brstrength`	`Gpars`	0.0 – 1.0	0.5	Brightness correction strength
`ccstrength`	`Gpars`	0.0 – 1.0	0.5	Color correction strength

## Modes

Value	Description
0 — Off	No enhancement
1 — Normal	Standard automatic correction
2 — No enhance + no manual CC	Disables enhancement and manual color correction
3 — Normal + no manual CC	Standard enhancement, manual color correction disabled

{% hint style="success" %} **Recommended:** Mode 1 with the default `brstrength` and `ccstrength` of 0.5. Disable only if you want VIESUS just for a single feature like AI upscaling. {% endhint %} # Global Color Correction Removes color casts and restores natural, balanced tones. These corrections are applied **globally**, across the entire image — as opposed to the targeted, per-zone adjustments in [Local Color Correction](/features/features/local-color-correction). ## Example {% columns %} {% column %} **Original**

Before — Color Correction — Shot through a car window with a green cast

{% endcolumn %} {% column %} {% endcolumn %} {% endcolumns %} {% columns %} {% column %} **Before**

{% endcolumn %} {% column %} **After**

After — Color Correction — Enhanced by VIESUS with `ccstrength = 0.5`

{% endcolumn %} {% endcolumns %} ## Parameters

Parameter	Section	Range	Default	Description
`ccstrength`	`Gpars`	0.0 – 1.0	0.5	Automatic color correction strength
`r`	`Gpars`	-1.0 – 1.0	0.0	Manual red channel balance
`g`	`Gpars`	-1.0 – 1.0	0.0	Manual green channel balance
`b`	`Gpars`	-1.0 – 1.0	0.0	Manual blue channel balance
`brightness`	`Gpars`	-1.0 – 1.0	0.0	Manual global brightness adjustment
`contrast`	`Gpars`	-1.0 – 1.0	0.0	Manual global contrast adjustment
`saturation`	`Gpars`	-1.0 – 1.0	0.0	Manual global saturation adjustment

{% hint style="warning" %} The manual channel and tone adjustments (`r`, `g`, `b`, `brightness`, `contrast`, `saturation`) are static and applied **at the end** of automatic processing, regardless of the analysis result. Adjust carefully — they can override otherwise correct automatic behavior. `ccstrength` is automatic and not affected. {% endhint %} {% hint style="success" %} **Recommended:** Keep `ccstrength` at default with Base Enhancement on. Reduce it for images that should retain a deliberate color cast. {% endhint %} # Local Color Correction Fine-tunes color, brightness, contrast, and saturation independently for three detected zones — **skin tones**, **sky**, and **vegetation**. {% hint style="info" %} **`Lpars.skin` targets a color range, not detected skin regions.** Warm, earthy tones like sand, desert rock, and sunset skies fall into this zone as well, not just skin. Change scene-specific adjustments within the dedicated [vScene](/features/scene-based-enhancement), not in the global defaults. A beach or sunrise often needs different `Lpars.skin` values than a portrait, and global values affect both equally. {% endhint %} ## Example {% columns %} {% column %} **Before**

Before — Color Zone Adjustments — Enhanced by VIESUS

{% endcolumn %} {% column %} **After**

After — Color Zone Adjustments — Enhanced by VIESUS with adjusted `Lpars.sky`

{% endcolumn %} {% endcolumns %} {% columns %} {% column %} **Before**

{% endcolumn %} {% column %} **After**

{% endcolumn %} {% endcolumns %} {% columns %} {% column %} **Before**

{% endcolumn %} {% column %} **After**

{% endcolumn %} {% endcolumns %} ## Per-zone parameters The same five parameters are configured independently for each zone. Each zone lives in its own sub-section: `Lpars.skin`, `Lpars.sky`, `Lpars.veg`.

Parameter	Range	Default	Description
`strength`	0.0 – 1.0	1.0	Overall strength of adjustments for the zone
`brightness`	-1.0 – 1.0	0.0	Brightness adjustment for the zone
`contrast`	-1.0 – 1.0	0.0	Contrast adjustment for the zone
`saturation`	-1.0 – 1.0	0.0	Saturation adjustment for the zone
`huerotation`	-10.0 – 10.0	0.0	Hue rotation for the zone

{% hint style="success" %} **Recommended:** Leave the per-zone adjustments at their defaults unless you need to target a specific color zone — VIESUS already balances skin, sky, and vegetation automatically. {% endhint %} # Skin Tone Enhancement ## Skin tone adjustment (`Lpars`) Skin tones are easy to overcorrect. VIESUS detects faces and prevents them from becoming oversaturated. ## Example {% columns %} {% column %} **Before (Skin)**

{% endcolumn %} {% column %} **After (Skin)**

{% endcolumn %} {% endcolumns %} ## Parameters

Parameter	Range	Default	Description
`skinToneAdjFac`	0.0 – 1.0	0.2	Saturation reduction (adaptive) in face regions (prevents "glowing" faces)

## Skin color zone (`Lpars.skin`) Fine-tune the skin tones globally. These parameters live in the `Lpars.skin` sub-section and use the same set as the other [local color corrections](/features/features/local-color-correction). {% hint style="info" %} **`Lpars.skin` targets a color range, not detected skin regions.** Warm, earthy tones like sand, desert rock, and sunset skies can fall into this zone too, not just skin. {% endhint %}

Parameter	Range	Default	Description
`strength`	0.0 – 1.0	1.0	Overall strength of adjustments for the skin zone
`brightness`	-1.0 – 1.0	0.0	Brightness adjustment for the skin zone
`contrast`	-1.0 – 1.0	0.0	Contrast adjustment for the skin zone
`saturation`	-1.0 – 1.0	0.0	Saturation adjustment for the skin zone
`huerotation`	-10 – 10	0.0	Hue rotation for the skin zone

{% hint style="success" %} **Recommended:** Leave `skinToneAdjFac` at 0.2 — it keeps faces from glowing while preserving natural color. Adjust the `Lpars.skin` zone only when you need to target skin tones specifically; VIESUS already balances them automatically. {% endhint %} # Shadow & Highlight Recovery Recovers detail in the darkest and brightest regions of an image — lifting blocked-up shadows and reining in blown-out highlights. The factors scale how strongly VIESUS corrects each region. ## Example {% columns %} {% column %} **Before**

{% endcolumn %} {% column %} **After**

{% endcolumn %} {% endcolumns %} ## Parameters

Parameter	Section	Range	Default	Description
`shadowfac`	`Lpars`	0.0 – 1.0	0.5	Shadow region correction factor
`highlightfac`	`Lpars`	0.0 – 1.0	0.5	Highlight region correction factor

{% hint style="success" %} **Recommended:** Leave both factors at 0.5 — VIESUS already balances shadow and highlight detail automatically. Raise a factor for stronger recovery in that region, or lower it to keep more of the original tonal contrast. {% endhint %} # Noise Reduction Reduces color grain and luminance grain. Four modes from off to strongest AI removal. ## Example {% columns %} {% column %} **Before**

{% endcolumn %} {% column %} **After**

{% endcolumn %} {% endcolumns %} ## Parameters

Parameter	Section	Value	Default	Description
`NoiseRedMode`	`Config`	0 – 3	0	Mode selection (see below)
`nrstrength`	`Gpars`	0.0 – 1.0	0.5	Color grain reduction strength
`nrmonostrength`	`Gpars`	0.0 – 1.0	0.5	Luminance grain reduction strength

## Modes

Value	Description
0 — Off	No denoising
1 — Automatic profiling	Estimates a noise profile for each image and applies appropriate denoising
2 — Fixed strength	Applies denoising based on `nrstrength` without per-image profiling. Can over-denoise low-noise images
3 — AI Noise Removal	Strongest AI model-based denoising (ignores `nrstrength` and `nrmonostrength`)

{% hint style="success" %} **Recommended:** Mode 1 for standard production. Mode 3 for images with heavy grain that the automatic profile underplays. {% endhint %} # Sharpening Local sharpening that enhances fine detail in textured areas (foliage, fabric, hair) while preserving smooth regions (sky, skin). ## Example {% columns %} {% column %} **Before**

{% endcolumn %} {% column %} **After**

{% endcolumn %} {% endcolumns %} ## Parameters

Parameter	Section	Value	Default	Description
`SHPmode`	`Config`	0, 1	1	Mode selection (see below)
`shplocalstrength`	`Gpars`	0.0 – 1.0	0.5	Local sharpening strength (textured regions)
`shpglobalstrength`	`Gpars`	0.0 – 1.0	0.0	Global sharpening strength

{% hint style="warning" %} `shpglobalstrength` is a manual correction: it is static and applied **at the end** of automatic processing, regardless of the analysis result. Adjust carefully — it can override otherwise correct automatic behavior. (`shplocalstrength` is automatic.) {% endhint %} ## Modes | Value | Description | | --------------- | ------------------------- | | **0** — Off | No sharpening | | **1** — Enabled | Standard local sharpening | {% hint style="success" %} **Recommended:** Keep enabled (mode 1) at the default local strength of 0.5. Leave global sharpening at 0 unless an image looks soft overall — it can introduce halos at high-contrast edges. {% endhint %} # Face Detection Detects faces and applies targeted enhancements to portrait regions. Required for [Face Reconstruction](/features/features/face-reconstruction), [Red-Eye Removal](/features/features/red-eye-removal), and [Adaptive Face Flash](/features/features/adaptive-face-flash). ## Example {% columns %} {% column %} **Before**

{% endcolumn %} {% column %} **After**

{% endcolumn %} {% endcolumns %} ## Parameters

Parameter	Section	Value	Default	Description
`FDmode`	`Config`	0 – 3	1	Mode selection (see below)
`fdstrength`	`Gpars`	0.0 – 1.0	0.5	Detection sensitivity — higher values detect smaller faces at the cost of processing time

## Modes

Value	Description
0 — Off	No face detection
1 — Normal	Face detection with landmarks
2 — Full analysis	Adds age estimation, blink detection, emotion recognition (SDK only)
3 — Blur faces	Blurs each detected face region for privacy protection

{% hint style="success" %} **Recommended:** Mode 1 for standard production. Increase `fdstrength` (e.g. 0.7 – 1.0) for group shots with small faces. {% endhint %} # Face Reconstruction AI-based reconstruction of facial features. Most effective for smaller faces in the frame where JPEG compression or low resolution has degraded facial detail. {% hint style="info" %} **Requires:** [Face Detection](/features/features/face-detection) — enabled automatically when this feature is active. {% endhint %} ## Example {% columns %} {% column %} **Before**

{% endcolumn %} {% column %} **After**

{% endcolumn %} {% endcolumns %} ## Parameters

Parameter	Section	Value	Default	Description
`FRmode`	`Config`	0 – 3	1	Mode selection (see below)
`frstrength`	`Gpars`	0.0 – 1.0	0.3	Reconstruction strength for smaller faces
`sfstrength`	`Gpars`	0.0 – 1.0	0.25	Small-face reconstruction importance (0.25 – 0.50 recommended)
`eyestrength`	`Gpars`	0.0 – 1.0	0.5	Eye detail emphasis

## Modes | Value | Description | | --------------- | -------------------------------------- | | **0** — Off | No face reconstruction | | **1** — Default | Standard reconstruction model | | **2** — Mixed | New default for AI upscaling workflows | | **3** — Fast | Slight quality trade-off for speed | {% hint style="success" %} **Recommended:** Mode 1 for general use; switch to Mode 2 when combining with [AI upscaling](/features/features/ai-super-resolution). Keep `sfstrength` between 0.25 and 0.50. {% endhint %} # Red-Eye Removal Detects and removes red-eyes caused by flash photography. {% hint style="info" %} **Requires:** [Face Detection](/features/features/face-detection) — enabled automatically when this feature is active. {% endhint %} ## Example {% columns %} {% column %} **Before**

{% endcolumn %} {% column %} **After**

{% endcolumn %} {% endcolumns %} ## Parameters

Parameter	Section	Value	Default	Description
`RERmode`	`Config`	0 – 2	0	Mode selection (see below)
`rerstrength`	`Gpars`	0.0 – 1.0	1.0	Detection strictness — higher values increase detection (and false positives)
`eyestrength`	`Gpars`	0.0 – 1.0	0.5	Eye detection strictness

## Modes

Value	Description
0 — Off	No red-eye removal
1 — Safe	Standard detection — minimises false positives
2 — Extended	More aggressive detection — catches more red-eye but more false positives

{% hint style="success" %} **Recommended:** Use Mode 1 (Safe) for flash photography — it minimises false positives. Switch to Mode 2 only if red-eye is being missed. {% endhint %} # AI Artifact Removal AI-based removal of JPEG compression artifacts, blocking, and ringing. Automatic detection mode applies removal only when artifact severity is above the activation threshold. {% hint style="warning" %} **Requires:** NVIDIA GPU for production throughput. CPU mode is available but significantly slower. {% endhint %} ## Example {% columns %} {% column %} **Before**

{% endcolumn %} {% column %} **After**

{% endcolumn %} {% endcolumns %} ## Parameters

Parameter	Section	Value	Default	Description
`ARmode`	`Config`	0 – 8	2	Mode selection (see below)
`arstrength`	`Gpars`	0.0 – 1.0	0.5	Activation threshold — higher value only triggers on more severely degraded images

## Modes

Value	Description
0 — Off	No artifact removal
1 — Auto, CPU	CPU-only DCT smoothing when artifacts detected
2 — Auto with AI (default)	Detects artifact severity, selects appropriate AI model
3 — Auto with AI, fast	Faster variant of Auto with AI
4 — Always CPU	Unconditional CPU-based DCT smoothing
5 — Always AI	Unconditional full-quality AI removal
6 — Always AI, fast	Unconditional fast AI removal
7 — Always CPU + AI	Combined CPU and AI passes
8 — Always CPU + AI, fast	Faster combined CPU and AI

{% hint style="success" %} **Recommended:** Mode 2 (Auto with AI) for general production. Use modes 5 – 8 only when you know every input has heavy compression artifacts. {% endhint %} # AI Upscaling AI upscaling by up to 4× per pass (up to 16× total with two-pass mode). Multiple speed/quality variants — the scene detection system can select the optimal model for the detected content type. {% hint style="warning" %} **Requires:** NVIDIA GPU (Ampere architecture or newer, ≥ 8 GB VRAM) for production throughput. {% endhint %} ## Example {% columns %} {% column %} **Source resolution**

{% endcolumn %} {% column %} **4× AI upscaling**

{% endcolumn %} {% endcolumns %} ## Parameters

Parameter	Section	Value	Default	Description
`ResizeMode`	`Resize`	0 – 12	5	Mode selection (see below)
`ResizeFacDetMode`	`Resize`	0 – 3	1	Size calculation mode. 0 = factor, 1 = small side, 2 = width, 3 = height
`ResizeFactor`	`Resize`	0.1 – 8.0	4.0	Resize factor (used when `ResizeFacDetMode` = 0)
`SupResThresh`	`Resize`	Float	2.0	SR only activates above this scale factor
`SupRes2xThresh`	`Resize`	Float	3.0	Scale-factor threshold up to which the 2× model is used; above it, the 4× model is applied

## Modes

Value	Description
0 — Default	Auto — selects algorithm based on content
1 — Bicubic	Bicubic interpolation
2 — Biquadratic	Biquadratic interpolation
3 — Bilinear	Bilinear interpolation
4 — Nearest Neighbour	Nearest neighbour interpolation
5 — AI SR ×4, quality	AI-based 4× super-resolution
6 — Default — no SR	Default without super-resolution
7 — AI SR ×2 / ×4, quality	Auto-selects 2× or 4× based on `ResizeFactor`
8 — AI SR ×2 / ×4, fast	Fast variant of mode 7
9 — AI SR ×4, fast	Fast 4× super-resolution
10 — AI SR ×2 fast / ×4 fast	Fast 2× or 4× (alternate path)
11 — AI SR ×4 with AR	AI 4× super-resolution with integrated artifact removal
12 — AI SR ×2 / ×4 Legacy	Legacy 2× and 4× super-resolution model

For the full Resize section reference (including `ResizeFacDetMode`, `ResizePixSize`, `ResizeOn`), see the [Parameter Reference → Resizing](/configuration/parameter-reference/resizing). {% hint style="success" %} **Recommended:** Mode 7 for quality-focused production. Mode 11 if input images have visible JPEG artifacts. {% endhint %} # Background Handling AI segmentation separates the subject from the background. Can add an alpha channel, replace the background with a solid color or custom image, or apply balancing between foreground and background. ## Example {% columns %} {% column %} **Before**

{% endcolumn %} {% column %} **After**

{% endcolumn %} {% endcolumns %} ## Parameters

Parameter	Section	Value	Default	Description
`BGmode`	`Config`	0 – 4	0	Mode selection (see below)
`BGBalmode`	`Config`	0 – 3	0	Balancing: 0 = off, 1 = to first, 2 = strict, 3 = to parameters
`ReplacePath`	`Background`	String	—	Path to a replacement background image (mode 3)
`backgroundR`	`Background`	0 – 255	255	Red component for solid-color replacement
`backgroundG`	`Background`	0 – 255	255	Green component for solid-color replacement
`backgroundB`	`Background`	0 – 255	255	Blue component for solid-color replacement
`balanceH`	`Background`	-1.0 – 1.0	0.0	Hue balance adjustment
`balanceS`	`Background`	-1.0 – 1.0	0.0	Saturation balance adjustment
`balanceV`	`Background`	-1.0 – 1.0	0.0	Value balance adjustment

## Modes

Value	Description
0 — Off	No background handling
1 — Alpha channel	Background made transparent
2 — Solid color replacement	Background replaced with `backgroundR/G/B`
3 — Image replacement	Foreground composited onto `ReplacePath`
4 — Alpha + solid color	Pre-composited RGBA

{% hint style="success" %} **Recommended:** Leave off (mode 0) for standard enhancement. Enable only for cut-outs or background replacement — Mode 1 for transparency, Mode 2 for a solid studio backdrop. {% endhint %} {% hint style="warning" %} **Output format:** Save as PNG or TIFF to preserve transparency. JPEG does not support alpha — modes 1 and 4 require a transparency-capable format. {% endhint %} # Background Blur Blurs the background while keeping the subject sharp, simulating a shallow depth of field. Uses depth map estimation. ## Example {% columns %} {% column %} **Before**

{% endcolumn %} {% column %} **After**

{% endcolumn %} {% endcolumns %} ## Parameters

Parameter	Section	Value	Default	Description
`BGBlurmode`	`Config`	0, 1	0	Mode selection (see below)
`blurstrength`	`Gpars`	0.0 – 1.0	0.0	Blur strength

## Modes | Value | Description | | --------------- | --------------------------- | | **0** — Off | No background blur | | **1** — Enabled | Computational bokeh applied | {% hint style="success" %} **Recommended:** Enable (mode 1) with `blurstrength` between 0.5 and 0.8 for natural results. {% endhint %} # Grain Addition Adds subtle film grain to reduce banding and posterisation in smooth gradient areas. Applied at the end of the pipeline. ## Example {% columns %} {% column %} **Before**

{% endcolumn %} {% column %} **After**

{% endcolumn %} {% endcolumns %} ## Parameters

Parameter	Section	Value	Default	Description
`GAmode`	`Config`	0, 1	0	Mode selection (see below)
`gastrength`	`Gpars`	0.0 – 1.0	0.5	Grain strength

## Modes | Value | Description | | --------------- | ------------------------- | | **0** — Off | No grain added | | **1** — Enabled | Applies subtle film grain | {% hint style="success" %} **Recommended:** Leave off for most images. Enable (mode 1, strength 0.5) when you see banding or posterisation in skies or other smooth gradients. {% endhint %} # Portrait Auto Cropping Automatically crops the image based on detected face position and configurable aspect ratio, headroom, and portrait mode. {% hint style="info" %} **Requires:** [Face Detection](/features/features/face-detection) for modes 1 and 2 — enabled automatically. {% endhint %} ## Example {% columns %} {% column %} **Before**

{% endcolumn %} {% column %} **After**

{% endcolumn %} {% endcolumns %} ## Parameters

Parameter	Section	Value	Default	Description
`CropMode`	`AutoCrop`	0 – 2	0	Mode selection (see below)
`AspectWidth`	`AutoCrop`	Float	1.0	Target aspect ratio width
`AspectHeight`	`AutoCrop`	Float	1.0	Target aspect ratio height
`Headroom`	`AutoCrop`	Float	0.106	General headroom
`HeadroomLeft`	`AutoCrop`	Float	0.106	Left-side headroom
`PortraitMode`	`AutoCrop`	0 – 2	2	Portrait cropping mode (largest face / all / auto)
`CropModeHeadroom`	`AutoCrop`	0, 1	0	Headroom alignment (centre / left)

## Modes

Value	Description
0 — Manual	Uses the configured aspect ratio and headroom values without face-based adjustment
1 — Automatic	Crops to the dominant detected face using the configured aspect ratio and headroom
2 — Group	Crops to include all detected faces (for group portraits)

For the full `AutoCrop` parameter set, see the [Parameter Reference → AutoCrop](/configuration/parameter-reference/background-and-cropping#portrait-auto-cropping-autocrop). {% hint style="success" %} **Recommended:** Use Mode 1 for single-subject portraits and Mode 2 for group shots. Set `AspectWidth`/`AspectHeight` to your output ratio; the default headroom (0.106) suits most headshots. {% endhint %} # White Fix Removes random grey dots in light and white areas — an artifact produced by printing techniques (e.g. inkjet) where very light regions develop noise patterns. ## Example {% columns %} {% column %} **Before**

{% endcolumn %} {% column %} **After**

{% endcolumn %} {% endcolumns %} ## Parameters

Parameter	Section	Value	Default	Description
`WFmode`	`Config`	0, 1	0	Mode selection (see below)

## Modes | Value | Description | | --------------- | ------------------------------------- | | **0** — Off | No white fix | | **1** — Enabled | Removes grey speckling in light areas | {% hint style="success" %} **Recommended:** Leave off for digital and screen output. Enable (mode 1) for print workflows — especially inkjet — where light areas show grey speckling. {% endhint %} # Adaptive Face Flash Applies subtle fill-flash simulation to underlit face regions, compensating for backlit or flash-free portraits. {% hint style="info" %} **Requires:** [Face Detection](/features/features/face-detection) — enabled automatically when this feature is active. {% endhint %} ## Example {% columns %} {% column %} **Before**

{% endcolumn %} {% column %} **After**

{% endcolumn %} {% endcolumns %} ## Parameters

Parameter	Section	Value	Default	Description
`AFFmode`	`Config`	0, 1	0	Mode selection (see below)
`addflashfac`	`Lpars`	0.0 – 1.0	0.5	Flash strength

## Modes | Value | Description | | --------------- | --------------------------------------------- | | **0** — Off | No fill-flash simulation | | **1** — Enabled | Applies adaptive fill-flash to underlit faces | {% hint style="success" %} **Recommended:** Enable (mode 1) and keep `addflashfac` at the default 0.5; lower it for a more subtle effect. {% endhint %} # ICC Color Management Controls the ICC color profile assigned to output images. ## Parameters

Parameter	Section	Value	Default	Description
`OutputProfileMode`	`ICCProfiles`	0 – 2	0	Mode selection (see below)
`OutputProfilePath`	`ICCProfiles`	String	—	Path to custom ICC profile (used when `OutputProfileMode = 2`)

## Modes

Value	Description
0 — Embed sRGB	Default — embeds sRGB ICC profile in output
1 — Preserve input profile	Keeps the input file's ICC profile in the output
2 — Embed custom profile	Uses the profile at `OutputProfilePath`

{% hint style="success" %} **Recommended:** Keep Mode 0 (embed sRGB) for web and general output. Use Mode 1 to preserve a wide-gamut input profile, or Mode 2 to embed a specific print profile. {% endhint %} # Monochrome & Sepia Converts output to black-and-white or a toned monochrome effect such as sepia. ## Example {% columns %} {% column %} **Original**

{% endcolumn %} {% column %} **Monochrome / Sepia**

{% endcolumn %} {% endcolumns %} ## Parameters

Parameter	Section	Value	Default	Description
`ForceToMonochrome`	`Other`	0, 1	0	Mode selection (see below)
`MonochromeToneR`	`Other`	-1.0 – 1.0	0.0	Red channel weight
`MonochromeToneG`	`Other`	-1.0 – 1.0	0.0	Green channel weight
`MonochromeToneB`	`Other`	-1.0 – 1.0	0.0	Blue channel weight

## Modes

Value	Description
0 — Off	Color output
1 — Enabled	Monochrome output (apply `MonochromeToneR/G/B` for sepia or other toning)

**Toning examples:** * `0.0, 0.0, 0.0` → neutral black and white * `0.15, 0.0, -0.20` → sepia # HDR Support VIESUS automatically detects HDR images and converts them to SDR output using tonemapping. When a gainmap is present, VIESUS can apply it directly — or use one of several dedicated tonemapping methods to achieve a better SDR rendition. {% hint style="info" %} The different `HDRmode` values are easiest to compare in the [VIESUS Viewer](/tools/viesus-viewer), which lets you switch between modes and preview the tonemapping result interactively. {% endhint %} ## Why HDR needs special handling Modern phone screens are bright enough to display high dynamic range content, so photos taken on a phone look punchy and alive on the device — a wider range of brightness than a typical monitor or print can reproduce. The catch: an HDR file actually carries two layers of data — a base image (usually SDR) plus a **gain map** that records the extra brightness information. On an HDR-capable display, the gain map is applied and you see the full range. On a non-HDR display or in print, only the base image gets used. That SDR base image is usually a compromise. Phone cameras typically either: * **Tonemap to preserve midtones** — highlights blow out to flat white, or * **Preserve highlights** — the whole image loses contrast and looks flat. Some cameras even produce intentionally flat SDR specifically so the HDR preview looks more impressive by comparison. Either way, the SDR fallback is missing information — and **contrast enhancement alone cannot recover it**. Contrast enhancement just shifts and stretches values that are already there; it can't reconstruct what wasn't recorded in the base image. VIESUS reads the full HDR data — base image plus gain map — and applies tonemapping. Tonemapping does two things at once: it shifts values **and** decides which highlights to preserve and which to clip, using the extended dynamic range as a guide. The result is an SDR output that keeps the crisp, non-flat character of the HDR original, so prints and standard monitors show a punchier, more accurate image than the camera's built-in SDR fallback. ## Example The same source at four output levels: the HDR image clipped at SDR range (preserves midtones), its SDR base image, and two VIESUS tonemapping results. {% columns %} {% column %} **HDR (clipped)**

{% endcolumn %} {% column %} **SDR (base)**

{% endcolumn %} {% endcolumns %} {% columns %} {% column %} **VIESUS tonemapped · HDRmode 1**

{% endcolumn %} {% column %} **VIESUS tonemapped · HDRmode 7**

{% endcolumn %} {% endcolumns %} ## Parameters

Parameter	Section	Range	Default	Description
`HDRmode`	`Config`	0 – 7	0	Mode selection (see below)
`hdrstrength`	`Gpars`	0.0 – 1.0	0.5	Tonemapping strength — blends the tonemapped result with the base SDR image

## Modes | Mode | Character | | ----------- | ------------------------------------------------------------------------------------------------------ | | **0** — Off | Uses the SDR base image (or computes SDR from the gainmap if the base is HDR) — no tonemapping applied | | **1** | Soft cinematic look — broadly forgiving default for mixed content | | **2** | Broadcast-standard tonemapping — predictable for video and broadcast workflows | | **3** | Dynamic metadata–aware — best when the source carries dynamic HDR metadata | | **4** | Reference knee curve — predictable mid-tones, soft highlight rolloff | | **5** | Smooth-gradient operator — can compress highlights heavily | | **6** | Smooth gradient with explicit white point — sharper highlight rendition | | **7** | High-contrast cinematic — popular for portraits and product shots | {% hint style="success" %} **Recommended:** Mode 1 as a general-purpose starting point — the default (Mode 0) applies no tonemapping. Try Mode 7 for portraits or product shots that benefit from contrast. {% endhint %} # Scene-Based Enhancement vScene detects the type of scene in each image and automatically applies parameter settings optimised for that scene; either VIESUS defaults or your own custom configuration per scene. Enhancement can be pushed further for scenes where stronger processing works well (greenery, blue sky, ...), while staying conservative where it doesn't (skin tones, night shots, ...). When [AI upscaling](/features/features/ai-super-resolution) is active, `VSceneMode=1` also enables scene-based 4× SR: landscape scenes without people are processed with the 4xAR model for sharper reconstruction. {% hint style="info" %} The easiest way to explore and fine-tune per-scene parameters is the [VIESUS Viewer](/tools/viesus-viewer). Load an image, see the detected scene type, and adjust parameters interactively per scene. {% endhint %} ## Example The same source image at four enhancement levels: the unprocessed original, VIESUS default enhancement (vScene off), and vScene at half and full strength. {% columns %} {% column %} **Original**

{% endcolumn %} {% column %} **VIESUS default**

VIESUS default — Scene-Based Enhancement

{% endcolumn %} {% endcolumns %} {% columns %} {% column %} **vScene · vscenestrength 0.5**

vScene strength 0.5 — Scene-Based Enhancement

{% endcolumn %} {% column %} **vScene · vscenestrength 1.0**

vScene strength 1.0 — Scene-Based Enhancement

{% endcolumn %} {% endcolumns %} ## Detected scene types vScene assigns each image the highest-priority scene type it matches (see table below). So a black-and-white architecture shot with a visible face is detected as **People** (priority 1 beats everything). Without a face, it's detected as **BlackWhite** (priority 2 beats Architecture's priority 4). The same logic applies to NightShot at priority 3. Within priority 4, scene types are mutually exclusive rather than ranked. An image showing both architecture and blue sky could be detected as either, depending on which content the scene detection weighs more heavily for that specific image. | Priority | Scene Type | Description | | -------- | -------------- | ------------------------------------------------------------------------------------- | | 1 | **People** | Images with visible faces — always takes priority, regardless of environment or color | | 2 | **BlackWhite** | Monochrome images without visible faces | | 3 | **NightShot** | Dark or night scenes, no faces detected | | 4 | Architecture | Buildings and urban environments | | 4 | Beach | Beach and coastal scenes | | 4 | BlueSky | Clear blue sky | | 4 | CloudySky | Overcast or cloudy sky | | 4 | Food | Food and beverage photography | | 4 | Greenery | Nature, plants, forests | | 4 | Landscape | General outdoor landscapes | | 4 | Snow | Snow-covered scenes | | 4 | SunsetSunrise | Golden hour and twilight | | 4 | Underwater | Underwater photography | | — | Other | Default when no other type matches | ## Parameters

Parameter	Section	Range	Default	Description
`VSceneMode`	`Config`	0, 1	0	Mode selection (see below)
`vscenestrength`	`Gpars`	0.0 – 1.0	1.0	Blends vScene-specific parameters with defaults. 0.0 = full default behavior; 1.0 = full vScene parameters applied

## Modes | Mode | Description | | --------------- | ----------------------------------------------------------------------------------------- | | **0** — Off | No scene-based adaptation; default parameters used for every image | | **1** — Enabled | Scene type detected; per-scene parameters applied (and scene-based 4× SR when applicable) | {% hint style="success" %} **Recommended:** Set `VSceneMode=1`. Leave `vscenestrength` at 1.0 unless you want a softer effect. {% endhint %} ## Custom per-scene parameters Beyond the built-in defaults, you can define your own parameter overrides per scene type directly in `viesusini.json`. Add a section named with a **`vScene_` prefix** followed by the scene type. For example `vScene_Landscape` or `vScene_People`. Only the parameters you list are overridden for that scene; everything else falls back to the top-level defaults. The `vScene_` prefix keeps scene names from clashing with the standard configuration sections; without it, the `Other` scene type would collide with the top-level `Other` section. {% hint style="info" %} **The easiest way to dial in per-scene settings is the VIESUS Viewer.** Enable vScene and pick a specific scene from the scene selector. The parameter sliders switch to that scene's values, and any image you enhance while a scene is selected has those values applied — regardless of the scene the image would actually be detected as. This lets you isolate, preview, and refine one scene's look at a time, then save the result to `viesusini.json`. {% endhint %} ```json { "Config": { "VSceneMode": 1 }, "vScene_Landscape": { "Gpars": { "shpglobalstrength": 0.3 }, "Lpars.sky": { "saturation": 0.1, "brightness": -0.25 }, "Lpars.veg": { "saturation": 0.1, "brightness": 0.25 } }, "vScene_People": { "Gpars": { "shplocalstrength": 0.3 }, "Lpars.skin": { "saturation": -0.05, "brightness": 0.25 } } } ``` ### Parameters you can set per scene Scene presets override only the **global (`Gpars`)** and **local (`Lpars`)** parameters listed below. Mode switches (`Config`), resizing, background handling, and output settings are global: they cannot be set per scene. **`Gpars` — global parameters** * Manual corrections: `brightness`, `contrast`, `saturation`, `r`, `g`, `b` * Strengths: `shpglobalstrength`, `shplocalstrength`, `nrstrength`, `nrmonostrength`, `gastrength`, `rerstrength`, `fdstrength`, `eyestrength`, `frstrength`, `blurstrength`, `dastrength` **`Lpars` — local parameters** * Whole image: `shadowfac`, `highlightfac`, `colorfac`, `skinToneAdjFac`, `addflashfac` * Per color zone (`Lpars.skin`, `Lpars.sky`, `Lpars.veg`): `huerotation`, `saturation`, `brightness`, `contrast`, `strength` See [Global Parameters](/configuration/parameter-reference/global-parameters) and [Local Parameters](/configuration/parameter-reference/local-parameters) in the Parameter Reference for what each parameter does and its range. # Native PDF Enhancement VIESUS enhances PDFs without flattening them. It opens the source PDF, locates the raster images embedded inside, enhances each one through the standard VIESUS pipeline, and writes the improved images back into a new PDF — preserving the document structure, fonts, layout, and vector elements. This means a photobook PDF, a marketing catalogue, or a print-ready document can be enhanced once at the production stage without anyone redoing the layout. ## Example {% columns %} {% column %} **Before**

{% endcolumn %} {% column %} **After**

{% endcolumn %} {% endcolumns %} ## What makes it "native" * **No flattening.** The PDF stays a PDF. Text remains text, vectors remain vectors, layers and metadata are preserved. * **Image-by-image enhancement.** Each embedded raster image is extracted, run through VIESUS, and written back. Non-image content is untouched. * **Tiled-image reconstruction.** Layout applications often split a single visual into many small image tiles. VIESUS recognises these split tiles, reassembles them into the single image they represent, and enhances the whole — avoiding visible seams where tile boundaries used to be. * **Background-image skipping.** Page-sized background images (decorative or full-page color backgrounds) can be detected and skipped so that only meaningful content images receive enhancement. ## How to use it Native PDF enhancement is delivered by the **VIESUS PDF Enhancer** — a separate command-line tool with stand-alone and hotfolder modes. The image enhancement parameters configured through `viesusini.json` apply to each embedded image; PDF-specific pipeline settings live in the PDF Enhancer's own `settings.json`. See the [PDF CLI reference](/reference/pdf-cli), [Installation](/installation/pdf), and [PDF Settings Reference](/configuration/pdf-settings). # Image Formats ## Image Formats VIESUS reads and writes the standard production image formats — JPEG, TIFF, PNG, WebP, and HEIC. RAW input is supported via an experimental loader. ### Supported formats

Format	Read	Write	Notes
JPEG	✓	✓	Quality controlled via `JpegComprQuality` (1 – 100; default 95)
TIFF	✓	✓	Supports alpha channel; common for print production
PNG	✓	✓	Supports alpha channel — required for Background Handling modes 1 and 4
WebP	✓	✓	Modern web format with alpha support
HEIC	✓	✓	iPhone / modern mobile capture; carries HDR gainmaps used by HDR Support
RAW	✓ (experimental)	—	Loaded via the experimental image loader (added in V10). Output is one of the above formats.

### Color modes

Color mode	Supported	Notes
RGB	✓	Default working color space
CMYK	✓	Added in V7.50; useful for print pipelines
Grayscale	✓	Added in V7.50
RGBA (with alpha)	✓	Required for Background Handling modes 1 and 4; preserve as PNG, TIFF, or WebP — JPEG does not support alpha

### Key caveats * **Alpha channel preservation** — save as PNG, TIFF, or WebP. JPEG drops alpha. See Background Handling for the modes that produce alpha output. * **ICC profile handling** — embedded ICC profiles in input images are honored. Output profile behavior is controlled by ICC Color Management. * **HDR gainmaps** — HEIC inputs (and some JPEGs) can carry gainmaps that HDR Support uses for SDR tonemapping. * **DPI metadata** — JPEG, TIFF, PNG and WebP carry DPI metadata. The `DPIResolutionSaveMode` parameter controls how VIESUS handles it on write — see Parameter Reference → Other. * **RAW loader** — experimental, format coverage varies by camera vendor. Verify your specific camera RAW format works before relying on it in production. ### Maximum dimensions and file size | Limit | Value | | --------------------- | --------------------------------------------------------------- | | Max input dimensions | No fixed library limit; constrained by available memory | | Max output dimensions | Same as input | | Cloud API file size | Images 20 KB – 50 MB; PDFs 20 KB – 1,000 MB. See Cloud: Credits | # Get a License VIESUS on-premise is commercially licensed. This page explains what to obtain from Viesus AG before installing. VIESUS on-premise products are commercially licensed. Contact to purchase or request a trial — Viesus AG will send you the software package along with your license details. A **GUID** license runs VIESUS across multiple machines, containers, or VMs — a unique GUID is delivered with your software package and passed at runtime. Request it when arranging your license. An **Activation Key** binds the license to a specific machine: you install the software, generate a request file from the target machine, and exchange it with Viesus AG for an activation file that unlocks the library on that machine. See [Licensing](/licensing/overview) for how each model works, full activation steps, and renewal. {% hint style="info" %} **Using VIESUS Cloud?** No license or installation is required. See [Quickstart: Cloud](/get-started/quickstart-cloud) to get started. {% endhint %} ## What you need before installing | What | Where to get it | Required for | | ---------------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------------------------------------------------- | | **Software package** (`.exe` or `.deb`/`.rpm`) | [transfer.viesus.com](https://transfer.viesus.com) | CLI, PDF Enhancer, Node.js module | | **GUID** | Delivered by Viesus AG when arranged | Deployments across multiple machines, containers, or VMs | | **Activation Key** | Generated from your target machine, exchanged with Viesus AG for an activation file | Fixed on-premise machines | | **Cloud API key** | [viesus.cloud/app/api-keys](https://www.viesus.cloud/app/api-keys) after creating a free account | VIESUS Cloud only | | **Trial license** | Request from | Evaluation before purchase | # Key Concepts The essential concepts behind VIESUS — one shared engine and configuration, how features are controlled, and GPU vs CPU. A few concepts make the rest of the documentation straightforward. Expand any that's new to you.

One engine behind every product

Every VIESUS product is a wrapper around the same C++ enhancement library — image analysis, correction algorithms, AI models, and output logic all live there. The wrappers just change how you invoke it. This matters in practice: prototype a configuration in the Viewer, then run it in production through the CLI or Node.js module, and you get identical results. Configure once, run anywhere. For a side-by-side comparison of every interface, see [Choose Your Interface](/discover/choose-your-interface). For direct library access, see the [C/C++ SDK](/reference/overview).

One configuration, every interface

All on-premise interfaces (CLI, PDF Enhancer, Node.js module, C/C++ SDK) read the same `viesusini.json` configuration file, with identical parameters. Tune a configuration in the VIESUS Viewer, export it, and use that exact file in production. Each feature is controlled the same way: a **mode** that turns it on or off (and sometimes selects a variant), plus a **strength** from `0.0` to `1.0` that sets how strongly it's applied. Once you know that pattern, the whole [Parameter Reference](/configuration/parameter-reference) reads consistently. ```powershell ┌─────────────────────────────────────┐ │ viesusini.json │ │ (your enhancement configuration) │ └──────────────┬──────────────────────┘ │ same file works with ┌───────┼───────────┐ ▼ ▼ ▼ CLI PDF CLI Node.js Module ```

GPU vs CPU, and optional AI features

VIESUS ships in two installer variants: **GPU** and **CPU**. | Variant | When to use | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | GPU installer | Systems with an NVIDIA GPU (Ampere architecture or newer, ≥ 8 GB VRAM). Enables full-speed AI features: AI upscaling, Artifact Removal, Background Handling. | | CPU installer | Systems without a compatible NVIDIA GPU. All standard enhancement (color, sharpening, noise, faces) works normally. AI-heavy features (AI upscaling, Artifact Removal) run significantly slower. | The AI features — AI upscaling, Artifact Removal, and Background — are **optional**. On Windows each is a separate add-on installer and is unlocked only if your license includes it (on Linux the models are bundled in the main package). Standard enhancement is always included and runs on either variant. See [AI Add-ons](/installation/add-ons) for installing the AI models and [Benchmarks](/operations/benchmarks) for processing-time reference data.

# Quickstart: Cloud Enhance your first image within 5 minutes using the VIESUS Cloud . No installation required — just a free account and a web browser. {% hint style="info" %} To use the VIESUS Cloud via API, see [Cloud API](/reference/cloud-api) {% endhint %} {% stepper %} {% step %} ### Create a free account Go to [viesus.cloud](https://www.viesus.cloud) and sign up. Every new account receives **200 free credits** {% endstep %} {% step %} ### Upload, enhance and download your images

{% endstep %} {% endstepper %} *** ## What's next * [Cloud API Overview](/reference/cloud-api/overview) — Full Cloud API documentation and architecture. * [Image Enhancement](/reference/cloud-api/image-enhancement) — All enhancement parameters and enum values. * [Webhooks](/reference/cloud-api/webhooks) — Receive push notifications instead of polling. * [Credits](/reference/cloud-api/credits) — Understand how credits are calculated and consumed. # Quickstart: Image Enhancement Enhance your first image with the VIESUS CLI on Windows or Linux. From download to enhanced output in under 10 minutes. Enhance your first image on-premise using the VIESUS CLI. This guide takes you from download to enhanced output. **Prerequisites:** Access to the [VIESUS Transfer Portal](https://transfer.viesus.com) with a valid [license](/licensing/overview) *** {% stepper %} {% step %} ## Install VIESUS Download the package for your platform from [transfer.viesus.com](https://transfer.viesus.com) and install it. Choose the GPU installer if you have an NVIDIA Ampere GPU with ≥ 8 GB VRAM; otherwise use the CPU installer. {% tabs %} {% tab title="Linux (amd64)" %} ```bash sudo dpkg -i viesus-redist__amd64.deb \ viesus__amd64.deb \ viesus-license__amd64.deb # Verify installation /usr/local/viesus/viesus -v ``` {% endtab %} {% tab title="Windows" %} Right-click `VIESUS_Viewer_and_CLI_Setup_VIESUS__GPU_x64.exe` → **Run as administrator**, accept the EULA, follow the wizard, restart when prompted. ```powershell # Verify installation "C:\Program Files\Imaging Solutions\VIESUS\viesus.exe" -v ``` {% endtab %} {% endtabs %} Expected output: `VIESUS X.XX.XX ...` (version matches the package you installed) {% hint style="info" %} For the full walkthrough with screenshots see [Installation](/installation/cli). {% endhint %} {% endstep %} {% step %} ## Activate your license After installing, activate your license on the target machine. * **GUID:** No activation step needed. Keep your GUID handy — you'll pass it to every command in the enhancement steps below. * **Activation Key:** Generate a request file with the VIESUS License Tool, send it to Viesus AG, and apply the activation file you receive back. Step-by-step with screenshots: [Licensing → Activation Key](/licensing/activation-key). No license yet? Contact to request a trial. {% endstep %} {% step %} ## Enhance your first image Process a single file. {% tabs %} {% tab title="Linux" %} ```bash /usr/local/viesus/viesus \ -p viesusini.json \ -s \ -f /path/to/photo.jpg ``` {% endtab %} {% tab title="Windows" %} ```powershell "C:\Program Files\Imaging Solutions\VIESUS\viesus.exe" ^ -p viesusini.json ^ -s ^ -f "C:\Photos\photo.jpg" ``` {% endtab %} {% endtabs %} {% hint style="info" %} **GUID users:** add `-g "your-guid"` to every command, e.g. `-g "4e8f35ab-7f72-4b1e-a1fd-2b5e9c58e9d3"`. Activation Key users omit the `-g` flag — the activated install unlocks the library at runtime. {% endhint %} The `-s` flag saves output in the same folder with a `_viesus` suffix: * Input: `photo.jpg` → Output: `photo_viesus.jpg` {% endstep %} {% step %} ## Process a batch Create an image list file (`images.lst`) with one path per line, then run VIESUS. {% tabs %} {% tab title="Linux" %} ```bash # Generate list from a folder find /path/to/photos -name "*.jpg" > images.lst # Process /usr/local/viesus/viesus \ -p viesusini.json \ -b /path/to/output \ -l images.lst ``` {% endtab %} {% tab title="Windows" %} ```powershell # Generate list from a folder dir /s /b /path/to/photos/*.jpg > images.lst # Process "C:\Program Files\Imaging Solutions\VIESUS\viesus.exe" ^ -p viesusini.json ^ -b "C:\Output" ^ -l images.lst ``` {% endtab %} {% endtabs %} A result file (`images.res`) is written alongside the list — one line per image with a status code. {% endstep %} {% endstepper %} *** ## Common issues at setup | Symptom | Cause | Fix | | ---------------------- | -------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | | License not recognised | GUID wrong or spaced / activation file not applied | For GUID users, check the `-g` value; for Activation Key see [Activation Key](/licensing/activation-key) | | `File not found` | Path in image list doesn't exist | Verify paths with `ls` or `dir` | | Slow AI features | GPU not detected | Run `nvidia-smi`; ensure you installed the GPU variant | | Permission denied | Output folder not writable | `chmod 775 /path/to/output` | # Quickstart: PDF Enhancement Enhance your first PDF document with the VIESUS PDF Enhancer on Windows or Linux. From install to enhanced output in under 10 minutes. Enhance your first PDF on-premise using the VIESUS PDF Enhancer. This guide takes you from installation to enhanced output. **Prerequisites:** Access to the [VIESUS Transfer Portal](https://transfer.viesus.com) with a valid [license](/licensing/overview) *** {% stepper %} {% step %} ## Install the PDF Enhancer Download from [transfer.viesus.com](https://transfer.viesus.com) and install. On Windows the VIESUS base package must be installed first; the Linux PDF Enhancer package bundles its own dependencies. {% tabs %} {% tab title="Linux (amd64)" %} ```bash sudo dpkg -i viesuspdf__amd64.deb sudo apt-get install -f # Verify /usr/local/viesuspdf/bin/viesuspdf -v ``` {% endtab %} {% tab title="Windows" %} {% stepper %} {% step %} Install `VIESUS_Viewer_and_CLI_Setup_VIESUS__GPU_x64.exe` (base package) first if not already installed. {% endstep %} {% step %} Install `VIESUS_PDFEnhancer__VIESUS_.exe` (right-click → **Run as administrator**, accept EULA, complete wizard). {% endstep %} {% endstepper %} ```powershell "C:\Program Files\Imaging Solutions\VIESUS\PDFEnhancer\viesusPDF.exe" -v ``` {% endtab %} {% endtabs %} Expected output: `viesusPDF X.XX.XX 64 bit ...` (version matches the package you installed) {% hint style="info" %} For the full PDF Enhancer install walkthrough see [Installation](/installation/pdf). {% endhint %} {% endstep %} {% step %} ## Activate your license After installing, activate your license on the target machine. * **GUID:** Add your GUID to the PDF Enhancer `settings.json` file. On Windows: `C:\Program Files\Imaging Solutions\VIESUS\PDFEnhancer\settings.json`. On Linux: `/usr/local/viesuspdf/settings.json`. ```json { "guid": "4e8f35ab-7f72-4b1e-a1fd-2b5e9c58e9d3" } ``` * **Activation Key:** Generate a request file with the VIESUS License Tool, send it to Viesus AG, and apply the activation file you receive back. Step-by-step with screenshots: [Licensing → Activation Key](/licensing/activation-key). No license yet? Contact to request a trial. {% endstep %} {% step %} ## Create an enhancement configuration Create `viesusini.json` with a minimal enhancement configuration: ```json { "Config": { "Enhancemode": 1, "NoiseRedMode": 1, "SHPmode": 1, "FDmode": 1, "RERmode": 1, "FRmode": 1, "ARmode": 2 }, "Other": { "JpegComprQuality": 95 } } ``` This enables color correction, noise reduction, sharpening, face detection, red-eye removal, face reconstruction, and AI artifact removal for each embedded image in the PDF. {% endstep %} {% step %} ## Enhance your first PDF Run in stand-alone mode, passing the source PDF, output folder, and your configuration file. {% tabs %} {% tab title="Linux" %} ```bash /usr/local/viesuspdf/bin/viesuspdf \ /path/to/document.pdf \ /path/to/output \ /path/to/viesusini.json ``` {% endtab %} {% tab title="Windows" %} ```powershell "C:\Program Files\Imaging Solutions\VIESUS\PDFEnhancer\viesusPDF.exe" ^ "C:\PDFs\document.pdf" ^ "C:\Output" ^ "C:\Config\viesusini.json" ``` {% endtab %} {% endtabs %} The PDF Enhancer writes two files to the output folder: | File | Description | | ------------------- | --------------------------------------------------------- | | `document_dest.pdf` | Enhanced PDF with improved embedded images | | `document.pdf.xml` | Processing report — image counts, statistics, error codes | The XML file is written last; you can use it as a completion signal in automated pipelines. {% endstep %} {% endstepper %} *** ## Common issues at setup | Symptom | Cause | Fix | | --------------------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | | License not recognised / no enhancement | GUID missing/incorrect in `settings.json`, or activation file not applied | For GUID, check the `guid` field in `settings.json`; for Activation Key, see [Activation Key](/licensing/activation-key) | | Output PDF identical to input | No qualifying images found | Check the XML report for image counts and skip reasons | | `viesusPDF` not found | Installation incomplete or PATH not set | Verify installation directory and restart the terminal | | Permission denied on output folder | Output folder not writable | `chmod 775 /path/to/output` (Linux) or check folder permissions (Windows) | # System Requirements Minimum and recommended hardware and software requirements for each VIESUS interface. The requirements below apply to on-premise installations. For VIESUS Cloud there is nothing to install — see the [Cloud API](/reference/cloud-api/overview) section. *** ## VIESUS CLI | Requirement | Windows | Linux | | ----------------------------- | ------------------------------------------------ | ---------------------------------------- | | OS | Windows 10 or later (x64) | Ubuntu 22.04 LTS or newer (x64 or arm64) | | Disk space | \~8 GB | Same | | RAM | 4 GB minimum; 16 GB for production | Same | | NVIDIA GPU (AI features only) | Ampere or newer; ≥ 8 GB VRAM; CUDA 12.6 or later | Same | | VIESUS package | `VIESUS_Viewer_and_CLI_Setup_*.exe` | Three `.deb` files from transfer portal | *** ## VIESUS PDF Enhancer | Requirement | Windows | Linux | | ------------------------- | ------------------------------------------- | ------------------------------- | | OS | Windows 10 or later (x64) | Ubuntu 22.04 LTS or newer (x64) | | RAM | 4 GB minimum; 16 GB+ for large PDFs | Same | | VIESUS base | VIESUS CLI packages must be installed first | Same | | PDF Enhancer package | `viesusPDF_Setup_*.exe` | `viesuspdf_*.deb` | | NVIDIA GPU (AI upscaling) | Ampere or newer; ≥ 8 GB VRAM | Same | *** ## VIESUS Node.js Module | Requirement | Value | | -------------------- | ------------------------------------------ | | OS | **Linux only** (Ubuntu 22.04 LTS, x64) | | Node.js | Version 18 or later | | VIESUS base packages | Must be installed before the npm module | | CUDA driver | 12.6 or higher (for GPU features) | | RAM | 1–2 GB per worker with AI features enabled | *** ## VIESUS C/C++ SDK | Requirement | Value | | --------------------- | --------------------------------------- | | OS | Windows x64, Linux x64, Linux arm64 | | Compiler | C++11 or later | | `IsEnhance.h` header | Request from | | VIESUS shared library | Included in the standard VIESUS package | *** ## VIESUS Cloud API | Requirement | Value | | ---------------- | -------------------------------------------------------- | | Account | Free account at [viesus.cloud](https://www.viesus.cloud) | | API key | Generated in the dashboard | | Internet access | Required (API calls to `api.viesus.cloud`) | | File size limits | Images: 20 KB – 50 MB; PDFs: 20 KB – 1,000 MB | | Starting credits | 200 free credits on new accounts | *** ## GPU quick-check Run this before installing. If GPU acceleration is needed: **Linux:** ```bash nvidia-smi ``` Look for `CUDA Version: 12.6` or higher in the output header. If `nvidia-smi` is not found or shows a lower CUDA version, [install or upgrade the NVIDIA driver](https://docs.nvidia.com/cuda/cuda-installation-guide-linux/). **Windows:** ```powershell nvidia-smi ``` Or check: **Device Manager → Display Adapters** → right-click → Properties → Driver version. {% hint style="danger" %} GPU acceleration requires an NVIDIA GPU with **Ampere architecture or newer** (RTX 3000 series, A-series, or newer). Older cards (GTX 10xx, 20xx) do not support CUDA 12.6. AMD and Intel GPUs are not supported. {% endhint %} *** ## What you can do without a GPU Everything except AI features works on CPU: | Feature | CPU | GPU required | | -------------------------- | ---- | --------------- | | Automatic color correction | ✓ | | | Noise reduction | ✓ | | | Sharpening | ✓ | | | Face detection | ✓ | | | Red-eye removal | ✓ | | | Classical upscaling | ✓ | | | AI Upscaling | Slow | ✓ (recommended) | | AI Artifact Removal | Slow | ✓ (recommended) | | Background Handling | Slow | ✓ (recommended) | For testing AI features without a local GPU, use [VIESUS Cloud](/reference/cloud-api/overview) — the GPU is hosted by Viesus AG. # CLI & Viewer Install the VIESUS CLI and Viewer on Windows or Linux, including the CPU and GPU installer variants. This guide installs the **VIESUS Viewer and CLI** base package — the foundation every Windows interface builds on. AI features (AI upscaling, Artifact Removal, Background) ship as separate add-on installers; see [AI Add-ons](/installation/add-ons) after completing this guide. License activation is covered under [Licensing → Activation Key](/licensing/activation-key). *** ## Choose your installer: CPU or GPU The base package comes in two variants — pick the one that matches your hardware:

Installer	Use when	Notes
`...GPU_x64.exe`	The machine has a compatible NVIDIA GPU	Full hardware-accelerated AI processing. Requires NVIDIA Ampere or newer with ≥ 8 GB GPU RAM.
`...CPU_x64.exe`	No compatible NVIDIA GPU	All standard enhancement works; AI features (AI upscaling, Artifact Removal) run far slower and aren't recommended for production batches.

{% hint style="info" %} Replace `` in all filenames below with the version number shown on the Transfer Portal download page (for example, `13.00.00`). {% endhint %} {% hint style="info" %} A **CLI-only** variant (`VIESUS_CLI_Setup_VIESUS__GPU_x64.exe`) installs the command-line tool without the Viewer, for headless servers. The steps below apply to either; only the Viewer component differs. {% endhint %} *** {% stepper %} {% step %} ## Install VIESUS {% tabs %} {% tab title="Windows" %} Download the installer that matches your hardware from the [VIESUS Transfer Portal](https://transfer.viesus.com), then right-click it and choose **Run as administrator**.

Available VIESUS installers in the Transfer Portal — The Transfer Portal lists the base Viewer + CLI installers, add-ons, the PDF Enhancer, and patches.

{% stepper %} {% step %} #### Accept the license agreement Read and accept the End-User License Agreement, then click **Next**. {% endstep %} {% step %} #### Select components The default **Full installation** includes the VIESUS License Tool, Commandline, FolderEnhancer, License Service, and Viewer. Leave all components checked unless you have a specific reason to exclude one, then click **Next**. {% endstep %} {% step %} #### Additional tasks Optionally check **Create desktop icons**, then click **Next**. {% endstep %} {% step %} #### License Service settings (conditional) This dialog appears **only** when the installer is launched from the command line with the `/NET` argument, for special network licensing setups: ```powershell VIESUS_Viewer_and_CLI_Setup_VIESUS__GPU_x64.exe /NET ``` In a standard installation this step is skipped. When it appears, leave **License Service Host Address** blank and keep the defaults (port `9090`, interface `127.0.0.1`), then click **Next**.

Show Screenshot

{% endstep %} {% step %} #### Ready to install Review the summary of selected components and tasks, then click **Install**. Wait while the installer extracts and installs all files. {% endstep %} {% step %} #### Finish and restart Click **Finish** to exit the Setup Wizard, then **restart Windows** before continuing to license activation. {% hint style="warning" %} A restart is required before license activation. Skipping it can cause activation failures. {% endhint %} {% endstep %} {% endstepper %} {% endtab %} {% tab title="Linux" %} VIESUS ships for Linux as `.deb` (Debian/Ubuntu) and `.rpm` (Red Hat/CentOS/Fedora) packages, for both x64 and arm64. The distribution is split into three packages — **all three must be installed**: | Package | Contents | | ---------------- | --------------------------------------------------------------- | | `viesus-redist` | Redistributable runtime libraries (OpenCV, shared dependencies) | | `viesus` | VIESUS CLI, enhancement library, and AI models | | `viesus-license` | License management tool (`DongleStatus_64_RS`) | {% hint style="info" %} On Linux the AI models are **bundled in the `viesus` package** — there are no separate add-on installers. The Windows add-ons described in [AI Add-ons](/installation/add-ons) do not apply. {% endhint %} Download all three packages from the [VIESUS Transfer Portal](https://transfer.viesus.com), then install: ```bash # Debian / Ubuntu — remove previous versions if present sudo dpkg -r viesus-license viesus viesus-redist sudo dpkg -i viesus-redist__amd64.deb \ viesus__amd64.deb \ viesus-license__amd64.deb ``` ```bash # Red Hat / CentOS / Fedora sudo rpm -e viesus-license viesus viesus-redist # remove old versions if present sudo rpm -ivh viesus-redist__x86_64.rpm \ viesus__x86_64.rpm \ viesus-license__x86_64.rpm ``` For arm64, use the `_arm64.deb` / `aarch64.rpm` package names. Full feature support requires an NVIDIA GPU; edge devices without a GPU run standard enhancement only. {% endtab %} {% endtabs %} {% endstep %} {% step %} ## Activate your license Once VIESUS is installed and the machine has been restarted, activate your license on the target machine. If you received a **GUID** (for deployments across multiple machines), no activation step on the install machine is required — the GUID is passed at runtime by each VIESUS interface. See [Licensing → GUID](/licensing/guid). With an **Activation Key**, generate a request file with the VIESUS License Tool, send it to Viesus AG, and apply the activation file you receive back. Step-by-step with screenshots: [Licensing → Activation Key](/licensing/activation-key). {% endstep %} {% step %} ## Verify the installation Open a command prompt and run: ```bash viesus --version ``` You should see something like `VIESUS X.XX.XX IF win 64 bit – Build …` (version matches the package you installed). If the command isn't found, check that the VIESUS install directory is on your `PATH`. For a complete first-run walkthrough including enhancing your first image, see [Quickstart: Image Enhancement](/get-started/quickstart-image-enhancement). {% endstep %} {% endstepper %} *** ## Troubleshooting If activation fails, the license isn't recognised, or the CLI can't find the library: * Confirm you **restarted** after install * Verify the activation file matches the request file you generated * Check that the `viesus_64.dll` you're calling matches the installed version (see [FAQ → GUID doesn't work](/support/faq#my-guid-doesnt-work-what-should-i-check)) * For more, see [Troubleshooting → First run](/support/troubleshooting#first-run) and [Troubleshooting → CLI](/support/troubleshooting#cli-and-image-enhancement) # AI Add-ons Install the VIESUS AI Upscaling, Artifact Removal, and Background AI add-on installers on Windows. On Windows, the AI features extend VIESUS through **separate add-on installers**, each one adding the model files for a specific feature. Run them **after** the base [CLI & Viewer](/installation/cli) installation. Every add-on is a small wizard: accept the EULA, install, finish. {% hint style="info" %} **A license for the feature is required.** Add-ons only take effect if the feature is part of your license. Contact to add features. {% endhint %} {% hint style="info" %} **Windows only.** On Linux the AI models are bundled in the `viesus` package — there are no separate add-on installers. See [CLI & Viewer → Linux](/installation/cli). {% endhint %} *** ## AI Upscaling `VIESUS_SuperResolution_AddOn_Setup_VIESUS_.exe` Installs the AI upscaling models for up to 16× resolution enhancement. Required to use the `SuperResolution` feature in processing configurations. {% hint style="warning" %} AI upscaling requires a compatible NVIDIA GPU (Ampere architecture or newer, minimum 8 GB GPU RAM). {% endhint %} {% stepper %} {% step %} ## Accept the license agreement Read and accept the EULA, then click **Next**. {% endstep %} {% step %} ## Ready to install Click **Install** to begin. {% endstep %} {% step %} ## Wait for installation The AI upscaling models are large — wait for extraction to complete. {% endstep %} {% step %} ## Finish Click **Finish**. {% endstep %} {% endstepper %} *** ## Artifact Removal `VIESUS_ArtifactRemoval_AddOn_Setup_VIESUS_.exe` Installs the AI model for JPEG artifact and compression-noise removal. Required to use the `ArtifactRemoval` feature in processing configurations. {% stepper %} {% step %} ## Accept the license agreement Read and accept the EULA, then click **Next**. {% endstep %} {% step %} ## Ready to install Click **Install** to begin. {% endstep %} {% step %} ## Finish Click **Finish**. {% endstep %} {% endstepper %} *** ## Background `VIESUS_Background_AddOn_Setup_VIESUS_.exe` Installs the AI background-handling model for computational bokeh and background blur/replacement. Required to use the `Background` feature in processing configurations. {% stepper %} {% step %} ## Accept the license agreement Read and accept the EULA, then click **Next**. {% endstep %} {% step %} ## Ready to install Click **Install** to begin. {% endstep %} {% step %} ## Finish Click **Finish**. {% endstep %} {% endstepper %} # PDF Enhancer Install the VIESUS PDF Enhancer on Windows and Linux. Includes GPU and CPU variants, verification steps, and release notes. The PDF Enhancer is a **separate installer** that requires an already installed and licensed [CLI & Viewer](/installation/cli) base package. See [System Requirements](/installation/requirements) for hardware, OS, and GPU requirements. *** ## Installation Download the PDF Enhancer from the [VIESUS Transfer Portal](https://transfer.viesus.com), then follow the steps for your platform. {% tabs %} {% tab title="Windows" %} Download `VIESUS_PDFEnhancer__VIESUS_.exe`, then right-click it and choose **Run as administrator**. {% hint style="info" %} Replace `` and `` with the version numbers shown on the Transfer Portal download page. {% endhint %} {% stepper %} {% step %} #### Accept the license agreement Read and accept the End-User License Agreement, then click **Next**. {% endstep %} {% step %} #### Select components The default **Full installation** includes VIESUS Tools and VIESUS PDFEnhancer. Click **Next**. {% endstep %} {% step %} #### Additional tasks Optionally check **Create desktop icons**, then click **Next**. {% endstep %} {% step %} #### Ready to install Review the summary of selected components and tasks, then click **Install**. {% endstep %} {% step %} #### Wait for installation to complete Wait while the installer extracts and installs all files. {% endstep %} {% step %} #### Finish Click **Finish** to exit the Setup Wizard. {% endstep %} {% endstepper %} #### Verify the installation Launching the program from the Start Menu runs it in **hotfolder mode**, displaying the viesusPDF version, build date, and VIESUS library version.

VIESUS PDF Enhancer in the Windows Start Menu

PDF Enhancer hotfolder mode start screen

You can also verify from the command line. Open `cmd.exe` as administrator, navigate to the install directory, and run `viesusPDF.exe -v`: ```powershell "C:\Program Files\Imaging Solutions\VIESUS\PDFEnhancer\viesusPDF.exe" -v ``` Expected output: ```powershell VIESUS PDFEnhancer Application X.XX.XX 64 bit VIESUS X.XX.XX win x86_64 bit Copyright (c) Viesus AG, 2011-2026 ``` {% endtab %} {% tab title="Linux" %} Download `viesuspdf__amd64.deb` from the [VIESUS Transfer Portal](https://transfer.viesus.com), then install: ```bash sudo dpkg -i viesuspdf__amd64.deb sudo apt-get install -f # resolve any dependencies # Verify /usr/local/viesuspdf/bin/viesuspdf -v ``` Expected output: ```powershell viesus@viesus-ddm:~$ /usr/local/viesuspdf/bin/viesuspdf -v Starting of /usr/local/viesuspdf/bin/viesuspdf AppDataPath is /usr/local/viesuspdf/bin viesusPDF X.XX.XX 64 bit - Build VIESUS X.XX.XX IW GPU lin x86_ 64 bit - Build GCb Copyright (c) Viesus AG, ``` {% endtab %} {% endtabs %} *** ## Changelog (selected versions) | Version | VIESUS | Key changes | | ------- | -------- | -------------------------------------------------------------------------------------- | | 4.06.00 | 13.00.00 | | | 4.05.00 | 12.00.00 | | | 4.04.04 | 11.00.01 | Handles PDF page dimensions beyond 32,767 pt; improved ICC profile handling | | 4.04.02 | 11.00.01 | Artifact removal added to resizing; soft mask resizing; stream reading for JPEG | | 4.04.00 | 11.00.00 | `justAnalyze` option added | | 4.03.00 | 10.00.00 | `noResize`, `-r targetRes`, `-T resizeThres` options; `viesusini.json` replaces `.ini` | | 4.00.00 | — | 64-bit; Linux port; GUID licensing | # Node.js Module Install the VIESUS Node.js native module on Ubuntu 22.04 with Node.js 18 and NVIDIA GPU support. {% hint style="info" %} **Linux Only** The VIESUS Node.js module is available on **Linux only**. {% endhint %} See [System Requirements](/installation/requirements) for hardware, OS, Node.js, and NVIDIA driver requirements. *** {% stepper %} {% step %} ## Install VIESUS ```bash sudo dpkg -i viesus-redist__amd64.deb \ viesus__amd64.deb \ viesus-license__amd64.deb sudo apt-get install -f ``` Verify NVIDIA driver: ```bash nvidia-smi ``` The CUDA version shown must be **12.6 or higher**. {% endstep %} {% step %} ## Install Node.js 18 ```bash curl -sL https://deb.nodesource.com/setup_18.x | sudo bash - sudo apt -y install nodejs ``` Verify: ```bash node --version # v18.x.x npm --version ``` {% endstep %} {% step %} ## Set up your project ```bash mkdir myproject && cd myproject npm init -y ``` Install the VIESUS native module from the local package: ```bash sudo npm install /usr/local/viesus/node-viesus ``` Install the worker thread pool helper: ```bash npm install node-worker-threads-pool --save ``` {% endstep %} {% step %} ## Copy example files ```bash cp -a node_modules/viesus/test/* . ``` This copies `testbatch.js`, `worker.js`, and a default `viesusini.json` into your project directory. Edit `testbatch.js` and insert your GUID: ```js const guid = "YOUR-GUID-HERE"; ``` {% endstep %} {% step %} ## Set thread pool size Set `UV_THREADPOOL_SIZE` before running. A good starting value is the number of CPU cores: ```bash export UV_THREADPOOL_SIZE=16 ``` {% endstep %} {% step %} ## Run a test ```bash mkdir in out # Copy some test images to ./in/ node testbatch.js ``` Output lines `> 0` indicate successful processing (value is processing time in ms). Negative values are error codes — see [API Reference](/reference/node.js-module/api-reference#error-codes). {% endstep %} {% endstepper %} # Updating Use the VIESUS Patch installer to update individual components, such as the Commandline tool, without a full reinstall. The **VIESUS Patch** is a lightweight installer (\~26.7 MB) that updates individual components — such as the Commandline tool — without reinstalling the full package. Use it to apply updates quickly between major releases. The Patch comes in CPU and GPU variants; use the one that matches your installed base package: * `VIESUS_Patch_Setup_VIESUS__GPU_x64.exe` * `VIESUS_Patch_Setup_VIESUS__CPU_x64.exe` {% hint style="info" %} The Patch updates an existing installation. Install the base [CLI & Viewer](/installation/cli) package first. {% endhint %} *** ## Apply a patch Download the patch from the [VIESUS Transfer Portal](https://transfer.viesus.com), then right-click it and choose **Run as administrator**. {% stepper %} {% step %} ## Accept the license agreement Read and accept the EULA, then click **Next**.

{% endstep %} {% step %} ## Select components Select only the components you want to update. **VIESUS Commandline** is pre-selected by default; uncheck anything that doesn't need updating, then click **Next**.

{% endstep %} {% step %} ## Additional tasks Desktop icons are unchecked by default for a patch update. Click **Next**.

{% endstep %} {% step %} ## Ready to install Review the selected components, then click **Install**.

{% endstep %} {% step %} ## Finish Click **Finish**.

{% endstep %} {% endstepper %} *** ## Verify the update Confirm the patched component reports the expected version: ```bash viesus --version ``` # Overview VIESUS licensing models — on-premise GUID and Activation Key, plus credit-based Cloud API. How each works and how to choose. VIESUS has two deployment models — **on-premise** and **cloud** — covering three distinct licensing mechanisms.

License type	Deployment	Best for	Details
GUID	On-premise	Deployments across multiple machines, containers, VMs, or cloud	GUID licensing
Activation Key	On-premise	Trials and fixed on-premise machines	Activation Key licensing
API Key + credits	Cloud	API-based integrations, no on-premise install	See below

*** ## On-premise licensing — GUID A unique GUID is delivered with the software package and passed at runtime to unlock the library. The GUID has no machine binding — the same GUID works on any number of systems simultaneously, including VMs, containers, and cloud instances. **Used for:** servers, Docker, Kubernetes, cloud infrastructure, anything that scales or moves between hosts. A GUID license is arranged with Viesus AG — discuss with when arranging your license. See [GUID](/licensing/guid) for the full mechanism, key properties, and how to pass the GUID in each VIESUS interface. *** ## On-premise licensing — Activation Key An Activation Key is bound to the target machine's hardware. After installation you generate a request file from the target machine and exchange it with Viesus AG for an activation file, which unlocks the library on that machine. **Used for:** trials, dedicated workstations, fixed on-premise production machines. See [Activation Key](/licensing/activation-key) for the step-by-step activation flow on Windows and Linux, including screenshots. *** ## Choosing between GUID and Activation Key | Scenario | Use | | ------------------------------------------------ | -------------- | | Servers, VMs, Docker containers, cloud instances | GUID | | Deployments that may scale or move | GUID | | Single fixed workstation or production server | Activation Key | | Trial or evaluation | Activation Key | Use a GUID when you need to run across multiple machines, in containers, or on cloud infrastructure where the activation hardware would change. Use an Activation Key for trials and fixed on-premise machines. *** ## Cloud licensing The VIESUS Cloud API uses a different model: **API key authentication** with **credit-based billing**. No library to install, no GUID, no expiry to manage. **How it works:** 1. Create an account at [viesus.cloud](https://www.viesus.cloud). 2. Generate an API key in the dashboard at `https://www.viesus.cloud/app/api-keys`. 3. Pass the key as `x-api-key` on every API request. 4. Credits are consumed per enhancement. **Credit model:** | Feature | Credits per image | | ------------------- | ----------------- | | Color Enhancement | 1 | | Restoration | 1 | | Background Handling | 4 | | AI Upscaling | 4 | When multiple features are active, only the highest-cost feature is charged. See [Cloud: Credits](/reference/cloud-api/credits) for PDF formulas and subscription tier details. *** ## Contact **On-premise licensing, renewals, or technical questions:** **VIESUS Cloud accounts:** [viesus.cloud](https://www.viesus.cloud) **Software downloads:** [transfer.viesus.com](https://transfer.viesus.com) # GUID GUID-based licensing for VIESUS on-premise products — machine-independent licensing, key properties, and how to pass the GUID at runtime. GUID-based licensing is used for deployments that run VIESUS across multiple machines — servers, Docker containers, VMs, or cloud instances where the activation hardware would change. For a single fixed machine, see [Activation Key](/licensing/activation-key). A GUID license is granted by Viesus AG when your deployment scenario warrants it. Discuss your scenario with when arranging your license. *** ## How it works Viesus AG delivers a customer-specific VIESUS library package with an expiry date embedded inside it. You provide a GUID — a unique identifier string — at runtime to unlock the library. The GUID has no machine binding; the same GUID works on any number of systems simultaneously. ```powershell Example GUID: 4e8f35ab-7f72-4b1e-a1fd-2b5e9c58e9d3 ``` Your GUID is delivered with your software package. Packages are downloaded from [transfer.viesus.com](https://transfer.viesus.com) or sent by email. Contact to request a trial or purchase. *** ## Key properties | Property | Detail | | --------------- | ----------------------------------------------------------------------------------- | | Machine binding | None — runs on any machine, VM, container, or cloud instance | | Billing | Volume-based: contracted by image count; enforcement is license-agreement dependent | | Expiry | Embedded in the delivered library; typically annual | | Grace period | 1–2 months of continued operation after expiry to allow renewal | | Renewal | Same GUID — install the new package; GUID does not change | | Trial | Available on request from | *** ## Volume and expiry On-premise licenses are contracted by image volume. The library tracks processed images against the contracted volume. When the limit is reached or the expiry date passes, images pass through without enhancement. The 1–2 month grace period ensures continuous operation during renewal. Viesus AG delivers a new library package with an updated expiry and volume; install it and processing resumes immediately. *** ## Passing the GUID The GUID is supplied at runtime by each VIESUS interface: **CLI:** ```bash viesus -g "4e8f35ab-7f72-4b1e-a1fd-2b5e9c58e9d3" -l images.lst -s -p config.json ``` **Node.js:** ```js const viesusObj = new viesus.MyViesusObject('4e8f35ab-7f72-4b1e-a1fd-2b5e9c58e9d3'); ``` **C/C++ SDK:** ```c HIsEnhance obj = IsEnhanceCreateFromGUID(IS_RGB, IS_PixelInterleaved, guidBytes); ``` **PDF Enhancer** — pass in `settings.json`: ```json { "guid": "4e8f35ab-7f72-4b1e-a1fd-2b5e9c58e9d3" } ``` # Activation Key Activation Key (Software Key) licensing for VIESUS — hardware-bound on-premise licensing, request file generation, and step-by-step activation. An **Activation Key** (also called a Software Key) binds the VIESUS license to a specific machine's hardware. It is used for trials and fixed on-premise machines. For deployments that need to scale across multiple machines, run in containers/VMs, or move between cloud hosts, see [GUID licensing](/licensing/guid) — granted on request when your scenario warrants it. *** ## How it works Each Activation Key is generated from your machine's hardware profile and is valid only on that exact hardware. The activation process has three steps: {% stepper %} {% step %} **Generate a RequestKey** — a VIESUS tool reads your hardware profile and produces a `requestkey.dat` file. {% endstep %} {% step %} **Send to Viesus AG** — email `requestkey.dat` to . {% endstep %} {% step %} **Receive and apply the ActivationKey** — Viesus AG returns `activationkey.dat` bound to your hardware. Apply it using one of the tools below. {% endstep %} {% endstepper %} {% hint style="warning" %} If the machine hardware changes significantly (CPU, motherboard), the Activation Key becomes invalid. Contact for re-activation. {% endhint %} *** ## Activation tools | Tool | Platform | Usage | | ------------------- | -------- | ------------------------------------------------------------------------------- | | VIESUS Viewer | Windows | `Help → Create License Request` to generate; `Help → Activate License` to apply | | VIESUS License Tool | Windows | Standalone offline tool for request and activation | | DongleStatusCmd | Linux | Command-line tool from the `viesus-license` package | *** ## Step-by-step activation on Windows VIESUS supports two activation methods on Windows. **Activation file** is the standard route for production deployments. **Web activation** is faster but requires a network connection from the license target machine. {% tabs %} {% tab title="Activation Key" %} {% stepper %} {% step %} ## Create a license request file Launch the VIESUS License Tool and click **Create Request File**.

Save with the suggested name.

A green success message confirms the file was created.

License request file created confirmation

{% endstep %} {% step %} ## Send the request to Viesus AG The request file is saved to your **Documents** folder by default. Email it to . Viesus AG will reply with a matching `.dat` activation file. {% endstep %} {% step %} ## Load the activation file When you receive your activation file:

Open License Tool to load activation file

1. Open the VIESUS License Tool 2. Click **Load Activation File…** 3. Select the `.dat` file you received

{% hint style="warning" %} The activation file name must match the request file you generated. Mismatched files won't activate. {% endhint %} 4. Click **Open** to apply. A confirmation appears at the bottom of the tool.

{% endstep %} {% step %} ## Verify the license Click **License Information** to see your active license details.

License Information dialog showing license details

{% endstep %} {% endstepper %} {% endtab %} {% tab title="Web activation" %} Use this method if your license target machine has internet access and you have a License ID. {% stepper %} {% step %} ## Launch the VIESUS License Tool

{% endstep %} {% step %} ## Open web activation Click **License Web Activation** to open the activation dialog.

Choose **Activate with License-ID**. {% endstep %} {% step %} ## Enter your details Enter your company information and click **Activate License**.

A green success message confirms activation.

{% endstep %} {% step %} ## Verify the license Click **License Information**.

License Information button after web activation

The dialog shows your license details.

{% endstep %} {% endstepper %} {% endtab %} {% endtabs %} *** ## Activation on Linux Use the `DongleStatus_64_RS` command-line tool from the `viesus-license` package: ```bash # Generate the request key file (send to info@viesus.com) DongleStatus_64_RS -r requestkey.dat # Apply the activation key received from Viesus AG DongleStatus_64_RS -a activationkey.dat # Check current license status DongleStatus_64_RS -s ``` # VIESUS Viewer The VIESUS Viewer is a Windows desktop application for visually tuning enhancement settings and testing configurations. The VIESUS Viewer is a Windows desktop application that runs the same enhancement engine as the CLI and any other module. It provides a visual before/after interface so you can tune `viesusini.json` parameters and immediately see the effect on real images — without writing any code or running command-line tools.

*** ## What the Viewer is for | Task | Use the Viewer | | -------------------------------------------------- | --------------------------------------- | | Visually compare before and after enhancement | Yes | | Tune parameters and see live results | Yes | | Export a tuned `viesusini.json` for production use | Yes | | Batch processing in production | Limited — use the CLI or Node.js module | The Viewer is not designed for production throughput. Use it to develop and validate your `viesusini.json` configuration, then use that same file with the CLI or Node.js module. *** ## Installing the Viewer The Viewer is included in the Windows installer package, see [CLI & Viewer](/installation/cli). *** ## Using the Viewer ### Loading an image {% stepper %} {% step %} Open the Viewer {% endstep %} {% step %} **File → Open** or drag an image file onto the window {% endstep %} {% step %} The unenhanced image appears in the left panel {% endstep %} {% endstepper %} ### Applying enhancement {% stepper %} {% step %} Open your `viesusini.json` via **File → Open Settings** (or create a new one) {% endstep %} {% step %} Click **Enhance** to process the image with the current settings {% endstep %} {% step %} The enhanced result appears in the right panel {% endstep %} {% step %} Use the slider or toggle to compare before and after {% endstep %} {% endstepper %} ### Tuning parameters Adjust parameters in the settings panel on the right side of the window: * Changes take effect on the next **Enhance** click * The underlying `viesusini.json` is updated as you adjust sliders * Save the updated configuration with **File → Save Settings** ### Exporting configuration for production After tuning in the Viewer, the saved `viesusini.json` file can be used directly with the CLI: ```bash viesus -p /path/to/viesusini.json -l images.lst -s ``` GUID-licensed deployments add `-g "$GUID"` to the command. Or with the Node.js module: ```js viesusObj.Enhance(fromPath, toPath, '/path/to/viesusini.json', resPath); ``` The Viewer, CLI, and Node.js module all read the same file format and produce identical output for the same input and settings. # Folder Enhancer The VIESUS Folder Enhancer is a Windows desktop application that watches hotfolders and automatically enhances images and PDFs as they arrive — no command line required. The VIESUS Folder Enhancer is a Windows GUI application built on top of the Image Enhancement CLI and the PDF Enhancer CLI. It watches one or more **hotfolders** — when a file lands in a watched folder, the Folder Enhancer automatically enhances it and writes the result to a configured destination folder. Because it drives both underlying CLIs, the Folder Enhancer handles both **images** (JPEG, TIFF, PNG, …) and **PDF documents** with embedded images.

VIESUS Folder Enhancer main window showing configured hotfolders and the operation log — The main window lists each configured hotfolder and shows live processing status in the operation log.

*** ## How hotfolders work Each hotfolder is an independent processing channel with its own configuration: | Setting | Description | | -------------------------- | ------------------------------------------------------------------------ | | **Source folder** | The folder to watch for incoming files | | **Destination folder** | Where enhanced output files are written | | **Enhancement parameters** | A `viesusini.json` configuration applied to every file in this hotfolder | | **File type** | Images, PDFs, or both | Each hotfolder is created and edited from the **Define Hotfolder** dialog, where you set the source and destination folders, the `viesusini.json` settings file, the input type (images or PDF), and options such as trigger files, batch size, and how to handle unsupported files.

Define Hotfolder dialog showing source, destination, and data settings — The Define Hotfolder dialog — source, destination, and the per-hotfolder settings file and input type.

You can define as many hotfolders as needed — for example one tuned for portrait photos, another for product images, and a third for PDF documents, all running simultaneously with different parameters. When a file appears in a source folder, the Folder Enhancer: 1. Detects the new file 2. Applies the enhancement settings configured for that hotfolder 3. Writes the enhanced file to the destination folder 4. Optionally archives or deletes the source file *** ## When to use the Folder Enhancer | Scenario | Use | | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- | | Automated enhancement without scripting or code | ✓ | | Different enhancement settings per file type or source | ✓ | | Integrating VIESUS into a Windows-based production workflow | ✓ | | Processing both images and PDFs from the same tool | ✓ | | Linux deployments or scripted pipelines | No — use the [CLI](/reference/cli-reference) directly | | Request-response or API-driven workflows | No — use the [Node.js module](/reference/node.js-module/overview) or [Cloud API](/reference/cloud-api/overview) | # Batch Processing How a high-volume photo lab enhances thousands of customer images per day with the VIESUS CLI — and which interface and settings fit the workflow. **The scenario:** A photo lab receives thousands of customer images per day across many orders. Images vary in size and quality, and every order must come back enhanced with consistent settings — without anyone editing images by hand. *** ## Recommended interface {% hint style="info" %} Use the [**VIESUS CLI**](/reference/cli-reference). It is built for unattended, high-volume batch processing on Windows or Linux servers and integrates into any script, scheduler, or orchestration tool. {% endhint %} The CLI reads a list of images (or a folder), applies one shared configuration to every image, and writes the enhanced files out. For interactive workloads behind a web service instead, see the [Node.js module](/use-cases/nodejs-saas); for PDFs, see [PDF Processing](/use-cases/pdf-photobook-workflow). *** ## How it works * You define one enhancement configuration (`viesusini.json`) and reuse it across the whole lab, so results stay consistent regardless of who runs the job. * The CLI processes a batch — a folder or an image list — in one run, writing each enhanced image to a destination folder. * A per-image result file records the status of every image, which your monitoring can scan to confirm an order completed cleanly. * Throughput scales by running more CLI instances in parallel — for example one per order, or one per GPU on a multi-GPU machine. *** ## What to consider | Factor | Guidance | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Hardware** | A compatible NVIDIA GPU is recommended for AI features (AI upscaling, Artifact Removal) and speed. Standard enhancement also runs on CPU. See [System Requirements](/installation/requirements). | | **Consistency** | Keep a single configuration per product type so every order is enhanced identically. | | **Throughput** | Plan capacity against your daily volume — see [Benchmarks](/operations/benchmarks) and [Performance Tuning](/operations/performance-tuning). | | **Scaling** | Parallelism comes from running multiple instances, not from one giant job. | | **Storage** | Enhanced output can be larger than compressed input — size your output storage accordingly. | | **Licensing** | A GUID suits servers that scale; an Activation Key suits a fixed machine. See [Licensing](/licensing/overview). | # PDF Processing How a print platform enhances photobook and catalogue PDFs automatically with the VIESUS PDF Enhancer — and which interface and settings fit the workflow. **The scenario:** A print production platform receives photobook and catalogue PDFs from customers. Each PDF contains many embedded images at print-insufficient resolution. The platform needs to upscale and enhance every embedded image, then route the finished PDF to the print queue — automatically, as files arrive. *** ## Recommended interface {% hint style="info" %} Use the [**VIESUS PDF Enhancer**](/reference/pdf-cli) in **hotfolder mode**. It works directly on PDFs — enhancing the embedded images while preserving layout, text, and vector content — and can run unattended as a watched-folder service. {% endhint %} The PDF Enhancer is the only interface that operates inside PDFs. For standalone image files use the [CLI](/use-cases/photo-lab-batch); for an API-driven cloud flow that also handles PDFs, see [Cloud API Integration](/use-cases/cloud-api-integration). *** ## How it works * A **hotfolder** watches an incoming directory. When a PDF lands, the enhancer analyses it, enhances (and optionally upscales) each qualifying embedded image to your target print resolution, and writes a new PDF to the output folder. * Source files can be archived automatically, and a per-file XML report records how many images were processed, enhanced, or skipped — and an error code you can check before routing to print. * It typically runs as a background service so the whole queue is processed without manual steps. A **standalone mode** is also available for one-off files or when you need to exclude specific pages. *** ## What to consider | Factor | Guidance | | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | **Mode** | Hotfolder for continuous queues; standalone for one-off files or page exclusions. | | **Target resolution** | Set the print DPI and cap the upscaling factor to avoid over-enlargement. | | **Classical vs AI upscaling** | Classical upscaling is fast and fine for most jobs; AI upscaling gives the best quality for premium products but needs an NVIDIA GPU and runs slower. | | **Filtering** | Background fills and very small images can be skipped so only real photos are enhanced. | | **GPU contention** | Run one instance per GPU to avoid out-of-memory errors. | | **Validation** | Always check the XML report's error code before sending a PDF to the print queue. | | **Limitations** | Password-protected PDFs can't be opened; very large PDFs need more memory. | # Node.js SaaS Integration How a SaaS platform enhances user-uploaded images in the background with the VIESUS Node.js module — and which interface and settings fit the workflow. **The scenario:** A SaaS platform lets users upload images that are enhanced in the background and made available to download. The service must handle many concurrent uploads without blocking, and keep enhancement off the main request path. *** ## Recommended interface {% hint style="info" %} Use the [**VIESUS Node.js module**](/reference/node.js-module/overview). It calls the enhancement engine **in-process** from Node.js via a worker thread pool, so enhancement runs off the main event loop without the overhead of launching an external process per image. {% endhint %} Choose this over the CLI when enhancement is part of a running Node.js service rather than a batch job. If you'd rather not host infrastructure at all, the [Cloud API](/use-cases/cloud-api-integration) offers the same engine over HTTP. *** ## How it works * The native module loads the VIESUS library inside your Node.js process. A pool of worker threads each holds one reusable enhancement instance, so requests are processed in parallel without blocking the event loop. * A typical service accepts an upload, hands the image to the pool, stores the enhanced result, and returns a link the user can retrieve — all asynchronously. * The same `viesusini.json` you tuned in the Viewer drives the enhancement, so results match your other interfaces. *** ## What to consider | Factor | Guidance | | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | **Platform** | The Node.js module is **Linux only**, and AI features need an NVIDIA driver with CUDA 12.6+. See [System Requirements](/installation/requirements). | | **Concurrency** | Size the worker pool to your CPU cores (or GPUs). Cap the queue so the service rejects early under overload rather than piling up. | | **Licensing** | The GUID is passed at runtime — keep it in an environment variable or secrets manager, never in source. | | **Output handling** | Clean up enhanced files on a TTL; don't rely on per-request deletion. | | **Resilience** | Set timeouts for very large images and track latency and queue depth. | | **Deployment** | Containerize for production — see [Docker Production Deployment](/use-cases/docker-production). | # Cloud API Integration How a web application enhances user-uploaded images with the VIESUS Cloud API — asynchronous, webhook-driven, no infrastructure — and which interface fits. **The scenario:** A web application lets users upload photos that are enhanced automatically and made available to download. Processing is asynchronous — users upload, are notified when the result is ready, and retrieve it — with no enhancement infrastructure to run and billing per image. *** ## Recommended interface {% hint style="info" %} Use the [**VIESUS Cloud API**](/reference/cloud-api/overview). It's a hosted GraphQL API — no library to install, no GPU to provision, no license to manage. You pay per enhancement and get AI features (including upscaling) without a local NVIDIA GPU. {% endhint %} Choose the Cloud when you don't want to operate servers. If you need on-premise processing or air-gapped operation, use the [CLI](/use-cases/photo-lab-batch) or [Node.js module](/use-cases/nodejs-saas) instead. *** ## How it works * **Upload** an image or PDF — either from a public URL, or via a signed upload URL so the browser uploads directly to VIESUS Cloud storage (keeping large files off your backend). * **Trigger enhancement** with the parameters you want. * **Get the result** by either polling the job status or — recommended for production — receiving a **webhook** when processing completes, then downloading the enhanced file. * Billing is **credit-based**, charged per enhancement. *** ## What to consider | Factor | Guidance | | ------------------ | -------------------------------------------------------------------------------------------------------- | | **Connectivity** | Requires internet access and file upload; not suitable for air-gapped environments. | | **Upload pattern** | The signed-URL flow avoids routing large files through your backend, reducing latency and egress cost. | | **Webhooks** | Prefer webhooks over polling at scale, and always verify the webhook signature before trusting an event. | | **Credits** | Track consumption and budget against your volume — see [Credits](/reference/cloud-api/credits). | | **Limits** | Requests are subject to API rate limits and file-size limits. | # Docker Production Deployment How to run VIESUS enhancement as a containerized GPU microservice — which interface to containerize and what to plan for in production. **The scenario:** A platform runs VIESUS-based enhancement as a containerized microservice on a GPU instance. It must restart automatically, update the license without rebuilding the image, and scale horizontally by adding more GPU instances. *** ## Recommended interface {% hint style="info" %} Docker isn't a separate interface — you containerize the interface you already use: the [**CLI**](/reference/cli-reference) for batch jobs, or the [**Node.js module**](/reference/node.js-module/overview) for a request-driven service. {% endhint %} This page covers the deployment concerns common to both. For the build details — Dockerfile, Compose, and run commands — see [Running the VIESUS CLI in Docker](/reference/docker/cli) and [Running the Node.js module in Docker](/reference/docker/nodejs). *** ## How it works * A GPU-enabled image is built on an NVIDIA CUDA base, with the VIESUS packages and your chosen interface installed. * The container is run with GPU access via the **NVIDIA Container Toolkit**, and the **GUID is supplied at runtime** (environment variable or secret) — never baked into the image. * A health check lets your orchestrator know when the service is ready, and logs are emitted to stdout for aggregation. * To scale, run **one container per GPU** and place a load balancer in front of them. *** ## What to consider | Factor | Guidance | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | **GPU access** | Requires Docker plus the NVIDIA Container Toolkit on the host. | | **GUID security** | Inject the GUID at runtime via an environment variable or secret; rotating it is just a restart, no rebuild. Never bake it into an image layer. | | **One GPU per container** | Run a single worker per GPU to avoid VRAM contention and out-of-memory errors. | | **Restart policy** | Use auto-restart so the service recovers from rare crashes. | | **Health checks** | Allow a start-up grace period — initialization takes a few seconds — so a healthy container isn't killed prematurely. | | **Image size** | A multi-stage build keeps the runtime image small. | | **Observability** | Aggregate stdout logs and watch GPU utilisation and latency. | # Overview All VIESUS on-premise interfaces (CLI, PDF Enhancer, Node.js module, C/C++ SDK) share the same **per-image enhancement** configuration file: `viesusini.json`. It defines how each image is enhanced — color, sharpening, AI upscaling, and the rest — and is documented in the [Parameter Reference](/configuration/parameter-reference). {% hint style="success" %} **You don't need to write one.** VIESUS enhances with sensible built-in defaults out of the box — if no `viesusini.json` is supplied, a default one is used for you. You only provide or edit a file when you want to change those defaults. {% endhint %} {% hint style="info" %} **The PDF Enhancer uses two files.** `viesusini.json` controls the enhancement applied to each embedded image (as above). The PDF Enhancer *also* has its own top-level `settings.json` that governs the **PDF pipeline** — watched folders, triggers, file handling, and resizing of embedded images. The two are separate: `settings.json` points to a `viesusini.json` for the actual enhancement. See the [PDF Settings](/configuration/pdf-settings) reference. {% endhint %} *** ## Where to start For most workflows you don't need to edit the configuration file by hand: * **Use a preset.** Pick the [preset](/configuration/presets-gallery) closest to your use case, download it, and run — no manual tuning needed for the common cases. * **Tune interactively.** Load a preset (or the defaults) into the [VIESUS Viewer](/tools/viesus-viewer), open a representative image, and change parameters live with before/after preview. Export the resulting `viesusini.json`. * **Edit the JSON directly.** When you know exactly which values you want, edit `viesusini.json` by hand — every parameter's type, default, and range is in the [Parameter Reference](/configuration/parameter-reference). # Presets Gallery Ready-to-use VIESUS enhancement preset configurations for common workflows. Download a JSON, drop it in, run. Each preset is a ready-to-use `viesusini.json` tuned for a specific workflow. Download the JSON, pass it to VIESUS with the `-p` flag (CLI), point your Folder Enhancer at it, or load it into the Node.js module. {% hint style="success" %} **Start with a preset, then customise.** The fastest way to get a working configuration is to take a preset close to your need and adjust the few parameters that matter for your case. The **VIESUS Viewer** lets you load a preset, preview its output, and tweak parameters interactively. {% endhint %} *** ## Available presets


Default	Standard automatic enhancement (color, contrast, brightness, sharpening, noise reduction) No AI upscaling vScene mode OFF CPU-only — no GPU required	default.json	placeholder.svg
vScene Enabled	Same as Default, plus scene-aware enhancement Per-scene tuning: Landscape, People, Night, Black & White, Beach, Snow, Sunset, etc. CPU-only	vscene-enabled.json	placeholder.svg
AI Upscaling (full)	4× AI upscaling AI Artifacts Removal (JPEG compression cleanup) AI Facial Reconstruction for natural high-res faces vScene ON, full color correction Requires GPU	ai-upscaling-full.json	placeholder.svg
AI Upscaling Only	4× upscaling without color correction Use when input is already color-corrected upstream Requires GPU	ai-upscaling-only.json	placeholder.svg
Background Removal	Removes background from portrait images Saves as PNG with transparent alpha channel No color correction or upscaling	background-removal.json	placeholder.svg
Background Removal + Enhance	Background removal plus full color correction Saves as PNG with transparent alpha channel Best for product photography and ID workflows	background-removal-enhance.json	placeholder.svg

{% hint style="info" %} Each preset is a complete `viesusini.json` — every parameter is present, so you can drop it in and run as-is, or open it and tune just the values you care about. The AI presets (upscaling, background removal) require an NVIDIA GPU; see the hardware notes below. {% endhint %} *** ## Customise a preset The fastest workflow: {% stepper %} {% step %} ### Pick the closest preset Start with a preset that's already close to what you need. Don't start from scratch unless you have a specific reason. {% endstep %} {% step %} ### Open in the VIESUS Viewer Load the JSON into the [VIESUS Viewer](/tools/viesus-viewer), open a representative image, and preview the output. {% endstep %} {% step %} ### Adjust the few parameters that matter For most cases, only a handful of parameters need tuning. The Viewer shows immediate before/after previews so you can iterate fast. {% endstep %} {% step %} ### Save and use it Save the customised JSON with a descriptive name (e.g. `photo-lab-workflow-xyz.json`) and use it. {% endstep %} {% endstepper %} For the full parameter reference, see [Configuration → Parameters](/configuration/parameter-reference). *** ## How to use a preset {% tabs %} {% tab title="CLI" %} Pass the preset path with `-p`: ```bash viesus -p default.json -s -f input.jpg ``` This enhances `input.jpg` and saves the result alongside it with the `_viesus` suffix. See the [CLI Reference](/reference/cli-reference) for all flags. {% endtab %} {% tab title="Folder Enhancer" %} Place the preset in your watched folder's config directory, or point the Folder Enhancer settings at it. See [PDF Enhancer Settings Reference](/configuration/pdf-settings) for the analogous PDF workflow. {% endtab %} {% tab title="Node.js Module" %} Load the JSON and pass the parsed object to the module: ```javascript const fs = require('fs'); const viesus = require('viesus'); const config = JSON.parse(fs.readFileSync('default.json', 'utf8')); await viesus.enhance({ input: 'input.jpg', output: 'output.jpg', config }); ``` See the [Node.js API Reference](/reference/node.js-module/api-reference) for the full signature. {% endtab %} {% endtabs %} # Parameters Complete reference for all viesusini.json parameters — Gpars, Lpars, Config, Resize, Background, ICCProfiles, AutoCrop, and Other. Complete `viesusini.json` parameter reference for VIESUS. All values are JSON. Providing a `viesusini.json` is **optional** — VIESUS enhances with built-in defaults when no file is supplied. Supply a file only to override specific defaults, and list just the parameters you want to change; everything omitted keeps its default. {% hint style="info" %} **How strength parameters work:** VIESUS automatically calculates the appropriate correction for each image. The strength parameters scale how much of the calculated correction is actually applied. This applies to all corrections, global and local. {% endhint %} For descriptions of what each feature does, see [Features](/features/features). For ready-to-use configurations, see the [Presets Gallery](/configuration/presets-gallery). {% hint style="info" %} **Easiest way to tune parameters interactively:** load your config into the [VIESUS Viewer](/tools/viesus-viewer), open a representative image, and adjust parameters live with before/after preview. {% endhint %} *** ## Configuration sections The `viesusini.json` file groups settings into sections. Each section has its own reference page: | Section | What it controls | Reference | | ------------------------ | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | | `Gpars` | Global correction strengths (brightness, color, sharpening, noise, AI features) and manual corrections | [Global Parameters](/configuration/parameter-reference/global-parameters) | | `Lpars` | Local corrections per region and per color zone (skin, sky, vegetation) | [Local Parameters](/configuration/parameter-reference/local-parameters) | | `Config` | Processing mode flags — which features are active, plus `ARmode`/`HDRmode` values | [Mode Switches](/configuration/parameter-reference/mode-switches) | | `Resize` | Upscaling mode, super-resolution, and target dimensions | [Resizing](/configuration/parameter-reference/resizing) | | `Background`, `AutoCrop` | Background replacement / color / balance, and portrait auto-cropping | [Background & Cropping](/configuration/parameter-reference/background-and-cropping) | | `Other`, `ICCProfiles` | Output format, JPEG quality, DPI, monochrome / sepia, and output ICC profile | [Output & Color](/configuration/parameter-reference/output-and-color) | The file also supports named **Scene Preset** sections (e.g. `vScene_Landscape`, `vScene_People`) that override selected defaults for specific content types. Each section name carries a `vScene_` prefix so the scene type can never clash with a standard section name — for example, the `Other` scene type would otherwise collide with the top-level `Other` section. VIESUS selects the active preset automatically when scene-aware enhancement (`VSceneMode`) is enabled — see the [vScene example](#scene-aware-enhancement-vscene) below. A `viesusini.json` generated by VIESUS (for example, exported from the VIESUS Viewer) also carries top-level `version` and `library` keys recording the build that wrote the file. These are informational only — leave them untouched or omit them. *** ## Passing the configuration file | Interface | How to pass the config | | -------------- | ---------------------------------------------------------------- | | CLI | `-p /path/to/viesusini.json` | | PDF Enhancer | Third positional argument: `viesusPDF src/ dest/ viesusini.json` | | Node.js module | `iniPath` parameter of `Enhance()` | | C/C++ SDK | Passed at initialization — see SDK docs | *** ## Common configuration examples Copy, adapt, and test from these starting points. For downloadable, ready-to-run files, see the [Presets Gallery](/configuration/presets-gallery). ### Standard photo enhancement (no resize) ```json { "Config": { "Enhancemode": 1, "NoiseRedMode": 1, "SHPmode": 1, "FDmode": 1, "RERmode": 1, "FRmode": 1, "ARmode": 2 }, "Other": { "JpegComprQuality": 95 } } ``` ### AI upscaling 2× (requires GPU) ```json { "Config": { "Enhancemode": 1, "SHPmode": 1, "FDmode": 1, "ARmode": 2 }, "Resize": { "ResizeOn": 1, "ResizeMode": 10, "ResizeFactor": 2.0 } } ``` ### Background removal to transparency (requires GPU, ≥8 GB VRAM) Removes the background to a transparent alpha channel — save the output as PNG. ```json { "Config": { "Enhancemode": 1, "SHPmode": 1, "FDmode": 1, "BGmode": 1 } } ``` To replace the background with a solid color instead, set `"BGmode": 2` and add a `Background` section with `backgroundR` / `backgroundG` / `backgroundB` (0 – 255). ### Conservative — gentle strengths, skip artificial images Skips artificial (non-photographic) images and applies lighter-than-default correction. ```json { "Config": { "Enhancemode": 1, "SHPmode": 1, "FDmode": 1, "SKIPmode": 0 }, "Gpars": { "brstrength": 0.3, "ccstrength": 0.3, "shpglobalstrength": 0.2 } } ``` ### Scene-aware enhancement (vScene) When `VSceneMode: 1` is set, VIESUS detects the scene type and applies the matching **Scene Preset** — only the parameters listed in a preset are overridden; all others fall back to the top-level defaults. Each preset section is named with a `vScene_` prefix followed by the scene type (e.g. `vScene_Landscape`). ```json { "Config": { "Enhancemode": 1, "VSceneMode": 1 }, "Gpars": { "brstrength": 0.5 }, "vScene_Landscape": { "Gpars": { "shpglobalstrength": 0.3 }, "Lpars.sky": { "saturation": 0.1, "brightness": -0.25 }, "Lpars.veg": { "saturation": 0.1, "brightness": 0.25 } }, "vScene_People": { "Gpars": { "gastrength": 0.5 }, "Lpars.skin": { "saturation": -0.05, "brightness": 0.1 } } } ``` See [Scene-Based Enhancement](/features/scene-based-enhancement) for more information and available scene types. *** ## Usage notes * **`0.5` strength is a balanced starting point** for most automatic applications. * **Face-related features need testing** in automated workflows — false positives can degrade results. * **Background manipulation requires verification** — automatic results are not always print-ready without QA. * **Super-resolution modes increase processing time significantly** but improve quality for upscaling scenarios. For ready-to-use starting configurations, see the [Presets Gallery](/configuration/presets-gallery). For PDF-specific settings, see the [PDF Enhancer Settings Reference](/configuration/pdf-settings). # Global Parameters The Gpars section — global enhancement strengths, specialised AI strengths, and manual corrections applied to the whole image. Global parameters control enhancement algorithms applied to the entire image. ## Enhancement strength VIESUS automatically calculates the appropriate correction for each image. The strength parameters scale how much of the calculated correction is actually applied.

Parameter	Range	Default	Description
`brstrength`	0.0 – 1.0	0.5	Brightness correction (most visible on underexposed images)
`ccstrength`	0.0 – 1.0	0.5	Color correction (removes color casts)
`shplocalstrength`	0.0 – 1.0	0.5	Local sharpening strength (visible in foliage, less in sky regions)
`nrmonostrength`	0.0 – 1.0	0.5	Noise reduction strength for monochrome images
`nrstrength`	0.0 – 1.0	0.5	Noise reduction strength for color images
`gastrength`	0.0 – 1.0	0.5	Grain addition strength (reduces banding/posterisation)

## Specialised enhancement

Parameter	Range	Default	Description
`rerstrength`	0.0 – 1.0	1.0	Red-eye reduction (higher values increase detection — and false positives)
`fdstrength`	0.0 – 1.0	0.5	Face detection sensitivity. Higher values detect smaller faces at the cost of processing time. Useful for group shots.
`eyestrength`	0.0 – 1.0	0.5	Eye detection strictness for red-eye correction
`frstrength`	0.0 – 1.0	0.3	Face reconstruction strength for smaller faces
`blurstrength`	0.0 – 1.0	0.0	Background blur / computational bokeh strength
`srstrength`	0.0 – 1.0	0.9	Super-resolution blending strength with default upscaling
`sfstrength`	0.0 – 1.0	0.25	Small-face reconstruction importance (0.25 – 0.50 recommended)
`dastrength`	0.0 – 1.0	0.5	Dark scene / night shot brightness correction
`arstrength`	0.0 – 1.0	0.5	AI Artifact Removal activation threshold. Higher = only triggers on more severely degraded images
`hdrstrength`	0.0 – 1.0	0.5	HDR tonemapping strength
`vscenestrength`	0.0 – 1.0	1.0	Blends the detected scene's parameters with the defaults. 0.0 = full default behavior; 1.0 = full vScene parameters applied

## Manual corrections {% hint style="warning" %} Manual corrections are static and applied **at the end** of automatic processing, regardless of the analysis result. Adjust carefully — they can override otherwise correct automatic behavior. {% endhint %}

Parameter	Range	Description
`brightness`	-1.0 – 1.0	Global brightness adjustment
`contrast`	-1.0 – 1.0	Global contrast adjustment
`saturation`	-1.0 – 1.0	Global saturation adjustment
`r`	-1.0 – 1.0	Red channel color balance
`g`	-1.0 – 1.0	Green channel color balance
`b`	-1.0 – 1.0	Blue channel color balance
`shpglobalstrength`	0.0 – 1.0	Global sharpening strength

# Local Parameters The Lpars section — region correction factors and per-zone adjustments for skin, sky, and vegetation. Local parameters control corrections applied to specific image regions. VIESUS automatically calculates the appropriate correction for each image. The strength parameters scale how much of the calculated correction is actually applied.

Parameter	Range	Default	Description
`highlightfac`	0.0 – 1.0	0.5	Highlight region correction factor
`shadowfac`	0.0 – 1.0	0.5	Shadow region correction factor
`colorfac`	0.0 – 1.0	0.5	Region-specific color correction factor
`skinToneAdjFac`	0.0 – 1.0	0.2	Saturation reduction in face regions (prevents "glowing" faces)
`addflashfac`	0.0 – 1.0	0.5	Adaptive shadow highlighting for faces (0.3 recommended)

## Color-specific adjustments VIESUS applies dedicated adjustments to three color regions important for image quality: **skin**, **sky**, and **vegetation**. Each lives in its own sub-section (`Lpars.skin`, `Lpars.sky`, `Lpars.veg`) and uses the same parameter set:

Parameter	Range	Default	Description
`huerotation`	-10.0 – 10.0	0.0	Hue rotation for the specific color region
`saturation`	-1.0 – 1.0	0.0	Saturation adjustment for the region
`brightness`	-1.0 – 1.0	0.0	Brightness adjustment for the region
`contrast`	-1.0 – 1.0	0.0	Contrast adjustment for the region
`strength`	0.0 – 1.0	1.0	Overall strength of adjustments for the region

# Mode Switches The Config section — which processing stages run, plus the ARmode and HDRmode value tables and feature dependencies. Controls which processing stages are enabled in the enhancement pipeline.

Parameter	Value	Default	Description
`ARmode`	0 – 8	2	Artifact removal. See ARmode values below.
`Enhancemode`	0 – 3	1	Enhancement mode. 0 = none, 1 = normal, 2 = no enhance + no manual CC, 3 = normal + no manual CC
`RERmode`	0 – 2	0	Red-eye reduction. 0 = disabled, 1 = safe, 2 = extended
`FDmode`	0 – 3	1	Face detection. 0 = off, 1 = normal, 2 = full analysis, 3 = blur faces (anonymise)
`SHPmode`	0, 1	1	Local sharpening. 0 = disabled, 1 = enabled
`NoiseRedMode`	0 – 3	0	Noise reduction. 0 = off, 1 = automatic profiling (recommended), 2 = fixed-strength (no profiling), 3 = AI Noise Removal
`SKIPmode`	0, 1	1	Skip artificial images. 0 = skip, 1 = enhance all
`WFmode`	0, 1	0	White fix. 0 = disabled, 1 = enabled
`FRmode`	0 – 3	1	Face reconstruction. 0 = off, 1 = default, 2 = mixed, 3 = fast
`AFFmode`	0, 1	0	Adaptive Face Flash. 0 = disabled, 1 = enabled
`ProcessingSequence`	0 – 3	0	Processing order. 0 = default, 1 = resize after, 2 = resize before, 3 = red-eye first
`GAmode`	0, 1	0	Grain addition. 0 = disabled, 1 = enabled
`BGmode`	0 – 4	0	Background handling. 0 = off, 1 = alpha, 2 = color replace, 3 = image replace, 4 = alpha + color (pre-composited RGBA)
`BGBlurmode`	0, 1	0	Background blurring. 0 = disabled, 1 = enabled
`BGBalmode`	0 – 3	0	Background balancing. 0 = off, 1 = to first, 2 = strict, 3 = to parameters
`VSceneMode`	0, 1	0	vScene scene-aware enhancement. 0 = off, 1 = on. Enables scene detection and Scene Preset selection automatically.
`HDRmode`	0 – 7	0	HDR tonemapping method. See HDRmode values below.

## `ARmode` values

Value	Description
`0`	Off
`1`	Auto, CPU-only DCT smoothing
`2`	Auto with AI (default) — detects artifact severity, selects appropriate model
`3`	Auto with AI, fast
`4`	Always CPU — unconditional CPU-based DCT smoothing
`5`	Always AI — unconditional full-quality AI removal
`6`	Always AI, fast
`7`	Always CPU + AI — combined CPU and AI passes
`8`	Always CPU + AI, fast

## `HDRmode` values

Value	Description
`0`	Off — no tonemapping
`1`	Soft cinematic look — broadly forgiving default
`2`	Broadcast-standard tonemapping — predictable for video / broadcast
`3`	Dynamic metadata–aware — best when source carries dynamic HDR metadata
`4`	Reference knee curve — predictable mid-tones, soft highlight rolloff
`5`	Smooth-gradient operator — can compress highlights heavily
`6`	Smooth gradient with explicit white point — sharper highlights
`7`	High-contrast cinematic — popular for portraits and product shots

## Feature dependencies Features that depend on another feature enable that dependency automatically at runtime — you do not need to set it yourself: | Feature | Requires | | ------------------------------- | ------------------------- | | Face Reconstruction (`FRmode`) | Face Detection (`FDmode`) | | Red-Eye Removal (`RERmode`) | Face Detection (`FDmode`) | | Adaptive Face Flash (`AFFmode`) | Face Detection (`FDmode`) | | Portrait Auto Crop (`CropMode`) | Face Detection (`FDmode`) | # Resizing The Resize section — image resizing, super-resolution, target dimensions, and the full list of resize mode values. Image resizing and super-resolution.

Parameter	Value	Default	Description
`ResizeOn`	0, 1	1	Enable / disable resizing
`ResizeFacDetMode`	0 – 3	1	Size calculation mode. 0 = factor, 1 = small side, 2 = width, 3 = height
`ResizePixSize`	Integer	6000	Target pixel size (depends on `ResizeFacDetMode`)
`ResizeFactor`	Float	4.0	Resize factor (depends on `ResizeFacDetMode`)
`ResizeMode`	0 – 12	5	Resize algorithm (see table below)
`SupResThresh`	Float	2.0	Super-resolution threshold factor
`SupRes2xThresh`	Float	3.0	Scale-factor threshold up to which the 2× super-resolution model is used; above it, the 4× model is applied
`SRNoiseInjection`	0, 1	0	Inject noise before super-resolution

## Resize mode values

Value	Method	Description
0	Default	Standard default resizing
1	Bicubic	Bicubic interpolation
2	Biquadratic	Biquadratic interpolation
3	Bilinear	Bilinear interpolation
4	Nearest Neighbor	Nearest neighbour interpolation
5	Super Resolution 4×	AI-based 4× super-resolution
6	Default — no SR	Default without super-resolution
7	Super Resolution 2× / 4×	AI-based 2× and 4× super-resolution
8	Super Resolution 2× / 4× Fast	Fast AI-based 2× and 4× super-resolution
9	Super Resolution 4× Fast	Fast AI-based 4× super-resolution
10	Super Resolution 2× Fast / 4× Fast	Fast AI-based 2× and 4× super-resolution (alternate)
11	Super Resolution 4× with Artifact Removal	AI 4× super-resolution with integrated artifact removal
12	Super Resolution 2× / 4× Legacy	Legacy 2× and 4× super-resolution model

# Background & Cropping The Background section (replacement, color substitution, balance) and the AutoCrop section (portrait auto-cropping). ## Background Handling (`Background`) Background replacement, color substitution, and balance.

Parameter	Value	Default	Description
`ReplacePath`	String	—	Path to a replacement background image
`backgroundR`	0 – 255	255	Red component for background color replacement
`backgroundG`	0 – 255	255	Green component for background color replacement
`backgroundB`	0 – 255	255	Blue component for background color replacement
`balanceH`	-1.0 – 1.0	0.0	Hue balance adjustment for background
`balanceS`	-1.0 – 1.0	0.0	Saturation balance adjustment for background
`balanceV`	-1.0 – 1.0	0.0	Value balance adjustment for background

*** ## Portrait Auto-Cropping (`AutoCrop`) Automatic cropping based on facial detection. See [Key Features → Adaptive Auto-Cropping](/discover/key-features#adaptive-auto-cropping).

Parameter	Value	Default	Description
`HeadYawCoeff`	Float	0.67	Coefficient for head yaw adjustment
`HeadPitchCoeff`	Float	0.75	Coefficient for head pitch adjustment
`HeadroomFixed`	0, 1	1	Use fixed headroom calculation
`HeadroomUnit`	Integer	0	Headroom unit type
`ImageToHeadRatio`	Float	0.48	Ratio of image to head size
`HeadroomLeft`	Float	0.1	Left side headroom
`Headroom`	Float	0.1	General headroom
`CropModeHeadroom`	Float	0.0	Headroom for crop mode
`AspectHeight`	Float	1.0	Target aspect ratio height
`AspectWidth`	Float	1.0	Target aspect ratio width
`PortraitMode`	Integer	2	Portrait cropping mode
`AdaptAspectRatioToFace`	0, 1	1	Adapt aspect ratio based on face detection
`AspectRatio`	Integer	0	Fixed aspect ratio mode
`CropMode`	0 – 2	0	Cropping mode (see CropMode values below)

### `CropMode` values

Value	Description
`0`	Manual — uses the configured aspect ratio and headroom values without face-based adjustment
`1`	Automatic — crops to the dominant detected face using the configured aspect ratio and headroom
`2`	Group — crops to include all detected faces (for group portraits)

# Output & Color The Other section (output format, JPEG quality, DPI, monochrome/sepia) and the ICCProfiles section (output color profile). ## Other Settings (`Other`) Miscellaneous output and processing options.

Parameter	Value	Default	Description
`WriteResultFiles`	0, 1	0	Create Excel result files
`JpegComprQuality`	1 – 100	95	JPEG compression quality
`DPIResolutionSaveDefault`	Float	72.0	Default DPI value
`DPIResolutionSaveMode`	0 – 5	0	DPI handling mode (see table below)
`ForceToMonochrome`	0, 1	0	Force monochrome output
`MonochromeToneR`	-1.0 – 1.0	0.0	Red tone for monochrome / sepia effects
`MonochromeToneG`	-1.0 – 1.0	0.0	Green tone for monochrome / sepia effects
`MonochromeToneB`	-1.0 – 1.0	0.0	Blue tone for monochrome / sepia effects
`ManualShadowFac`	0.0 – 1.0	0.0	Manual shadow factor override

### DPI resolution save modes For image formats that store DPI metadata, the following modes control how VIESUS handles it.

Value	Description
0	Save always and keep DPI value on resize
1	Save only if available and keep DPI on resize
2	Save default value to all images
3	Never save DPI information
4	Save always — keep image size on resize in cm / inch
5	Save only if available — keep image size on resize in cm / inch

*** ## ICC Profiles (`ICCProfiles`) ICC color profile handling.

Parameter	Value	Default	Description
`OutputProfileMode`	0 – 2	0	Profile mode. 0 = sRGB, 1 = same as input, 2 = custom profile
`OutputProfilePath`	String	—	Path to custom ICC profile (used when `OutputProfileMode = 2`)

# PDF Settings The PDF Enhancer's settings.json — general behavior, resizing, folders, triggers, file extensions, and special rendering modes. The VIESUS PDF Enhancer uses a JSON **`settings.json`** file for its pipeline: general processing behavior, resizing, folder paths, the trigger workflow, file naming, and special rendering modes. {% hint style="info" %} **`settings.json` vs `viesusini.json`.** `settings.json` governs the **PDF pipeline** — which folders to watch, how files are handled, triggers, and the resizing of embedded images. The **per-image enhancement** applied to each extracted image (color, sharpening, AI upscaling, etc.) is controlled separately by `viesusini.json` — see the [Parameter Reference](/configuration/parameter-reference). {% endhint %} **Default path on Windows:** `C:\Program Files\Imaging Solutions\VIESUS\PDFEnhancer\settings.json`. Changes take effect on the next hotfolder start (or immediately in stand-alone mode). For boolean parameters, **0** = OFF, **1** = ON. *** ## Settings groups | Group | What it controls | Reference | | ------------------ | --------------------------------------------------------------------------- | ---------------------------------------------------------------------- | | General | Core processing behavior, image filtering, adjacency and soft-mask handling | [General](/configuration/pdf-settings/general) | | Resizing | Image resizing, AI Upscaling, and artifact-removal modes | [Resizing](/configuration/pdf-settings/resizing) | | Folders & Triggers | Source / destination / archive folders and the file-based trigger workflow | [Folders & Triggers](/configuration/pdf-settings/folders-and-triggers) | | File Extensions | Naming conventions for processed and archived files | [File Extensions](/configuration/pdf-settings/file-extensions) | | Special Functions | Render to Image (RTI) and Render to PDF (RTPDF) | [Special Functions](/configuration/pdf-settings/special-functions) | *** ## Troubleshooting For PDF-specific error codes, see [PDF Error Codes](/support/error-codes/pdf). For CLI exit codes from the underlying enhancement engine, see [CLI Exit Codes](/support/error-codes/cli). | Symptom | Likely cause / fix | | ----------------------- | ---------------------------------------------------------------------------------------------- | | **File not found** | Verify all paths exist and are accessible to the PDF Enhancer process | | **Permission denied** | Ensure exclusive read access to source files and write access to dest/archive folders | | **Invalid JSON** | Check syntax and parameter values against this reference | | **Port conflict** | Use `-p` to specify an alternative port if the default (12033) is in use | | **Memory errors** | Reduce `maxFactor` or `maxTargetSize`; process smaller batches | | **Images not enhanced** | Verify `minFileSize`, `minImageWidth`, `minImageHeight`, and resize `threshold` | | **Trigger not working** | Confirm the trigger filename matches the `trigger` parameter and the folder is being monitored | # General General PDF Enhancer settings — core processing behavior, image filtering, adjacency, and soft-mask handling. Core configuration for PDF processing behavior.

Parameter	Type	Default	Description
`viesusIni`	String	-	Path to the VIESUS image enhancement configuration file. Default path is `C:\ProgramData\Imaging Solutions\VIESUS\PDFEnhancer\IsEnhance.json`
`archive`	Boolean	1	Enable / disable archiving of processed files
`delete`	Boolean	1	Enable / disable deletion of source files after processing
`debug`	Boolean	1	Enable / disable debug mode and logging
`minFileSize`	Integer	20	Minimum PDF file size (KB) for processing
`destFileLog`	Boolean	0	Enable destination file logging
`useColorRatio`	Boolean	0	Enable color ratio analysis for artificial image detection
`colorRatioThres`	Float	0.05	Threshold for color ratio analysis
`checkAdjacentImages`	Boolean	1	Check for adjacent images to merge for enhancement
`adjacencyThres`	Integer	10	Threshold for determining image adjacency (pixels)
`overlapThres`	Integer	10	Threshold for determining image overlap (pixels)
`includeSoftMaskedImages`	Boolean	1	Enable enhancement of images with soft masks
`streamReading`	Boolean	1	Enable JPEG stream reading (disable for files with zipped images)
`skipFullPageBackground`	Boolean	1	Skip background images that fill the entire page
`minImageWidth`	Integer	64	Skip images narrower than this
`minImageHeight`	Integer	64	Skip images shorter than this

{% hint style="info" %} For boolean parameters: **0** = OFF, **1** = ON. {% endhint %} {% hint style="warning" %} * **`checkAdjacentImages`** should be disabled for very complex PDFs to avoid performance issues {% endhint %} # Resizing PDF Enhancer resizing settings — image resizing, AI Upscaling, and artifact-removal modes for embedded images. Image resizing and AI Upscaling behavior for embedded images.

Parameter	Type	Default	Description
`enable`	Boolean	1	Enable / disable image resizing
`mode`	Integer	0	Resizing mode (see Parameter Reference → Resize modes)
`threshold`	Float	1.2	Resize factor required to trigger AI Upscaling
`targetResolution`	Integer	300	Target resolution in DPI
`maxFactor`	Float	16.0	Maximum allowed resize factor
`maxTargetSize`	Float	500.0	Maximum output file size (MB)
`removeArtifacts`	Boolean	0	Enable artifact removal processing
`arMode`	Integer	2	Artifact removal mode (see below)

## Artifact removal modes

Mode	Behavior	Description
0	Off	No artifact removal
1	Automatic	AI decides when to apply artifact removal
2	Always on	Apply artifact removal to all images

# Folders & Triggers PDF Enhancer folder paths and the file-based trigger workflow for hotfolder processing. ## Folder configuration Folder paths for the PDF processing workflow.

Parameter	Type	Default	Description
`srcFolder`	String	`C:\ProgramData\…\PDFHotFolder`	Source folder for input PDF files
`destFolder`	String	`C:\ProgramData\…\PDFDestFolder`	Destination folder for processed PDFs
`archiveFolder`	String	`C:\ProgramData\…\ArchiveFolder`	Archive folder for original files
`statusFolder`	String	`C:\ProgramData\…\PDFDestFolder`	Status folder for processing logs
`debugFolder`	String	`""`	Debug folder for diagnostic files

#### Folder requirements * All folders must exist and be accessible to the PDF Enhancer process * Source folder is monitored continuously for new PDF files * Archive folder stores originals when archiving is enabled * Debug folder contains diagnostic data only when `debug = 1` *** ## Trigger configuration File-based processing triggers and completion notifications.

Parameter	Type	Default	Description
`trigger`	String	`order.ready`	Name of the trigger file to monitor
`removeTrigger`	Boolean	0	Remove trigger file after processing
`renameTrigger`	Boolean	1	Rename trigger file during processing
`outTrigger`	String	`""`	Output trigger file name (signals completion to downstream systems)

#### Trigger workflow {% stepper %} {% step %} ### Drop trigger file Your upstream system places a file matching the `trigger` name (default `order.ready`) in the source folder once all PDFs for the order have been written. {% endstep %} {% step %} ### Enhancer picks it up The PDF Enhancer detects the trigger file, then processes all PDFs in the source folder. {% endstep %} {% step %} ### Trigger handling After processing, the trigger file is renamed (default) or deleted depending on `renameTrigger` and `removeTrigger` settings. {% endstep %} {% step %} ### Optional completion signal If `outTrigger` is set, a completion file is written to the destination folder for downstream systems to detect. {% endstep %} {% endstepper %} # File Extensions PDF Enhancer naming conventions for processed and archived files. Naming conventions for processed and archived files.

Parameter	Type	Default	Description
`destExtension`	String	`_dest`	Suffix appended to output filenames
`archiveExtension`	String	`_arc`	Suffix appended to archived filenames
`tempDestPrefix`	String	`""`	Prefix for temporary destination files

## Example naming | File | Result | | ------- | ------------------- | | Input | `document.pdf` | | Output | `document_dest.pdf` | | Archive | `document_arc.pdf` | # Special Functions PDF Enhancer special rendering modes — Render to Image (RTI) and Render to PDF (RTPDF). ## Render to Image (RTI) Convert PDF pages to image files instead of enhancing them in-place.

Parameter	Type	Default	Description
`renderToImage`	Boolean	0	Enable PDF → image conversion
`renderToImageDPI`	Integer	301	DPI resolution for rendered images
`renderToImageStartPage`	String	`""`	Starting page number for conversion

## Render to PDF (RTPDF) Rebuild a PDF from enhanced images.

Parameter	Type	Default	Description
`renderToImageToPDF`	Boolean	0	Enable image → PDF conversion
`renderToImageToPDFSinglePages`	Boolean	1	Create single-page PDF files

# CLI Reference Complete reference for the VIESUS image enhancement CLI — flags, input methods, output naming, image list format, and usage examples. The `viesus` command-line tool is the most common interface for batch image enhancement on Windows and Linux. It reads image files (singly or by list), applies the VIESUS enhancement pipeline, and writes output — built to be called from shell scripts, schedulers, or any orchestration tool. This page documents every flag, input method, and output convention. To run it in a container see [Docker for CLI](/reference/docker/cli); for throughput data see [Benchmarks](/operations/benchmarks), and for fixes see [Troubleshooting](/support/troubleshooting). ## Syntax ```bash viesus [options] [-l imagelist | -f file1 [file2 ...]] ``` {% hint style="warning" %} The `-f` option must be the **last** parameter on the command line — everything after it is treated as input files. {% endhint %} *** ## Input methods

Method	Flag	Description
File list	`-l <imagelist>`	Process images listed in a text file (one path per line)
Direct files	`-f <file1> [file2 ...]`	Process specified image files directly

*** ## Core options

Flag	Argument	Description
`-b <path>`	String	Base path for saving enhanced image results
`-p <file>`	String	Path to parameter/configuration JSON file
`-i`	—	Save enhanced images with the same filename (overwrites the original)
`-s`	—	Save enhanced images in the same folder with default suffix `_viesus`
`-n <suffix>`	String	Save enhanced images with a custom suffix. Only valid when `-b` is not used.
`-e`	—	Enhance only images containing valid EXIF data
`-a`	—	Force re-enhancement of already processed images (not recommended)
`-T <n>`	Integer	Number of worker threads. Defaults to physical CPU core count.

## Information options

Flag	Description
`-I`	Display license information. For GUID libraries, the GUID must be specified using `-g GUID`.
`-v`	Display VIESUS library version
`-h`	Show help information

*** ## Output behavior When processing images, VIESUS writes a results text file alongside the enhanced images. The file contains one line per processed image with its error code, plus processing statistics.

Input source	Results file name
`-f` direct files	`Images.res`
`-l ImageList.lst`	`ImageList.res`

*** ## Output naming

Flag combination	Example input	Example output	Location
`-s`	`photo.jpg`	`photo_viesus.jpg`	Same folder as input
`-n "_custom"`	`photo.jpg`	`photo_custom.jpg`	Same folder as input
`-b "output" -s`	`photo.jpg`	`photo_viesus.jpg`	`output/` folder
`-i`	`photo.jpg`	`photo.jpg`	Same location (overwrites)

{% hint style="warning" %} **`-i` overwrites the original.** Back up source images before using it. There is no undo. {% endhint %} *** ## Image list format The simplest image list has one image path per line: ```powershell C:\Photos\image1.jpg C:\Photos\image2.png D:\Pictures\vacation\sunset.jpg ``` You can also specify a destination path per image using a pipe separator: ```powershell C:\Photos\image1.jpg|D:\Output\image1_enhanced.jpg C:\Photos\image2.png|D:\Output\image2_enhanced.png ``` ### Creating an image list {% tabs %} {% tab title="Windows" %} ```powershell # All JPG files recursively dir /b /s *.JPG > Images.lst # Multiple extensions dir /b /s *.jpg *.png *.tiff > Images.lst # Specific folder dir /b "C:\Photos\*.jpg" > Images.lst ``` {% endtab %} {% tab title="Linux" %} ```bash # All JPG files recursively find /path/to/images -name "*.jpg" > images.lst # Multiple extensions find /path/to/images $ -name "*.jpg" -o -name "*.png" $ > images.lst ``` {% endtab %} {% endtabs %} *** ## Examples ### Process a folder of images with a config ```bash # Create image list (Windows) dir /b /s *.JPG > Images.lst # Process using image list viesus -l Images.lst -s -p "TempFolder\Viesus_Configuration.json" -n "_myConfig" -b "TempFolder" ``` ### Process individual files with a custom suffix ```bash viesus -s -n "_enhanced" -p "config.json" -f image1.jpg image2.jpg image3.jpg ``` ### Process files and save to a different directory ```bash viesus -b "C:\output" -s -p "settings.json" -f "C:\input\photo.jpg" ``` ### Professional batch — EXIF-filtered, custom suffix, 8 threads ```bash viesus -l photos.lst -e -s -n "_pro" -p "professional.json" -b "enhanced" ``` *** ## Best practices * **Use image lists for large batches** — calling `-f` with thousands of files exceeds command-line length limits on Windows. * **Test on a small subset first** — validate your config before kicking off a 100,000-image run. * **Back up before `-i`** — it overwrites originals with no recovery path. * **Monitor disk space when using `-b`** — output files can match or exceed source size, especially after AI Upscaling. * **Use `-e` to skip non-photographic images** — improves throughput when the source contains screenshots or graphics. ## Performance tips * **Batch size**: process in batches that fit in memory rather than passing one giant list. * **Storage**: use SSD storage for both input and output paths to avoid I/O bottlenecks. * **Parallelism**: run multiple CLI instances in parallel rather than increasing threads inside one — single-threaded is fastest per image. See [Performance Tuning](/operations/performance-tuning). * **Network paths**: avoid processing over SMB / NFS where possible — copy locally, process, copy back. * **EXIF filtering**: `-e` saves time on heterogeneous source folders. For deeper guidance, see [Operations → Performance Tuning](/operations/performance-tuning) and [Benchmarks](/operations/benchmarks). # PDF CLI VIESUS PDF Enhancer (viesusPDF) reference — operating modes, all flags, processing workflow, and usage examples. The VIESUS PDF Enhancer (`viesusPDF`) processes PDF documents containing embedded images. It opens the PDF, locates each embedded image, applies VIESUS enhancement (and optionally AI upscaling), writes the improved images back into a new PDF, and outputs a processing report. The document structure, layout, fonts, and vector elements are preserved — only the embedded raster images change. PDF pipeline settings (hotfolder paths, resizing, file handling) live in the PDF Enhancer's own `settings.json` — see the [PDF Settings Reference](/configuration/pdf-settings). The per-image enhancement parameters come from `viesusini.json` (the [Parameter Reference](/configuration/parameter-reference)), exactly as with the image CLI. *** ## When to use the PDF Enhancer Designed for PDFs from layout applications where images are embedded but not pre-rendered — typically photobooks, marketing catalogs, and print-ready files. It is **not** suitable for: * Flattened / rasterized PDFs (all content is already pixels) * Selectively enhancing only specific pages or elements — the enhancer processes all qualifying images * Real-time request-response use — use the [Node.js module](/reference/node.js-module/overview) or [VIESUS Cloud](/reference/cloud-api/overview) *** ## Operating modes `viesusPDF` runs in two modes: * **Stand-alone** — process a file or folder once, from the command line. Suitable for scripted pipelines and one-time processing. * **Hotfolder** — monitor a configured folder continuously and process PDFs as they arrive. Runs as a long-lived background process for print-production workflows. *** ## Information

Flag	Description
`-v`	Print version information and exit

*** ## Hotfolder mode Monitors a configured folder for new PDF files and processes them as they arrive. Use this for continuous production pipelines. ```bash viesusPDF -h [-g ] [options] ```

Flag	Required	Description
`-h`	Yes	Start in hotfolder mode
`-g <guid>`	Optional	Start with a specific GUID (only for GUID-licensed libraries)

**Examples:** ```bash # Start hotfolder viesusPDF -h # Start with specific GUID viesusPDF -h -g 12345678-1234-1234-1234-123456789abc ``` Hotfolder behavior (watched folder, trigger files, archive paths) is configured in `settings.json`. See the [PDF Settings Reference](/configuration/pdf-settings). *** ## Stand-alone mode Process one file or one folder of PDFs directly from the command line. ```bash viesusPDF [options] ``` ### Required positional arguments

Position	Argument	Description
1	`<source>`	Path to PDF file or source folder
2	`<destFolder>`	Path to destination folder for processed files
3	`<viesusIniFile>`	Path to JSON file containing VIESUS enhancement settings

### Optional arguments Optional flags can appear in any order after the required arguments. #### File handling

Flag	Type	Description
`deleteSrc`	Flag	Delete source files after successful processing
`archive <path>`	String	Archive original files to the specified folder
`useSoftMasked`	Flag	Enable processing of images with soft masks
`justAnalyze`	Flag	Analyse and count images only (results go to status file)

#### Page processing

Flag	Format	Description
`-s <pages>`	String	Skip specified pages (stand-alone mode only)

**Page skip format:** | Token | Meaning | | ------ | -------------------- | | `f` | First page | | `l` | Last page | | Number | Specific page number | Example: `-s f,l,5,10,14` skips first, last, and pages 5, 10, 14. #### Network and debugging

Flag	Type	Default	Description
`-p <portNr>`	Integer	`12033`	Port number for TraceConsumer

#### Image processing

Flag	Type	Default	Description
`noResize`	Flag	Off	Disable resizing of small images
`-r <targetRes>`	Integer	`300`	Target resolution in DPI for size calculations
`-T <resizeThres>`	Float	`1.2`	Minimum factor required to trigger resizing

*** ## Examples ### Basic processing ```bash viesusPDF "C:\input\document.pdf" "C:\output" "C:\config\enhance.json" ``` ### With archive and source deletion ```bash viesusPDF "C:\input\document.pdf" "C:\output" "C:\config\enhance.json" deleteSrc archive "C:\archive" ``` ### Skip specific pages ```bash viesusPDF "C:\input\document.pdf" "C:\output" "C:\config\enhance.json" -s "1,3,5" ``` ### Analysis only ```bash viesusPDF "C:\input\document.pdf" "C:\output" "C:\config\enhance.json" justAnalyze ``` ### Custom resolution and resize threshold ```bash viesusPDF "C:\input\document.pdf" "C:\output" "C:\config\enhance.json" -r 600 -T 1.5 ``` ### Production batch with all options ```bash viesusPDF "C:\batch\pdfs" "C:\enhanced" "C:\settings\config.json" deleteSrc archive "C:\backup" useSoftMasked -r 400 -T 1.3 -p 15000 ``` *** ## Processing workflow ```mermaid flowchart LR A[PDF Input] --> B[PDF Enhancer] B --> C{For each\nembedded image} C --> D[VIESUS Enhancement\n± AI Upscaling] D --> E[Write back to PDF] E --> F[Enhanced PDF Output] B --> G[XML Processing Report] ``` 1. PDF opened and analyzed 2. Each embedded raster image is extracted 3. VIESUS enhancement applied (color, sharpening, noise reduction, face processing) 4. Optional AI upscaling to target print resolution 5. Enhanced images written back into the PDF structure 6. Enhanced PDF and XML report written to the destination *** ## Output files

File	Description
`<filename>_dest.pdf`	Enhanced PDF with improved images
`<filename>.pdf.xml`	Processing report: image counts, statistics, error codes

The XML file is written last — an upstream system can watch for it as a completion signal. *** ## Argument details ### Source path * **File** — processes a single PDF * **Folder** — processes every PDF in the directory The source must be accessible and contain valid PDFs. ### Destination folder Must exist or be creatable by the application. Processed PDFs are written here with the same internal structure as the source. ### Configuration file A JSON file containing VIESUS enhancement parameters. See the [PDF Settings Reference](/configuration/pdf-settings) for the full schema. ### Archive behavior When `archive ` is specified, originals are copied to the archive folder **before** processing. The archive folder is created if it doesn't exist. ### Page skipping Stand-alone mode only. Useful for excluding cover pages, blank pages, or known non-image content. Pages are numbered from 1. ### Resize logic * Images below the target resolution are candidates for resizing. * `-T resizeThres` is the minimum scale factor required to trigger enhancement — below this, the image is left untouched. * `noResize` disables resizing entirely. *** ## Platform support | Platform | Support | | ------------------------- | ------- | | Windows 10 / Server 2016+ | ✓ | | Ubuntu 22.04+ | ✓ | | Linux arm64 | ✓ | *** ## Best practices * **Validate paths** before kicking off a batch — broken paths waste hours. * **Use folder input for batches** — better throughput than scripting one-PDF-at-a-time. * **Archive originals** for important workloads. Disk is cheap; lost source PDFs are expensive. * **Set resize thresholds appropriately** — too low wastes compute; too high misses beneficial enhancements. * **Monitor memory** with large PDFs that contain many embedded images. ## Performance considerations * **Memory** — large PDFs with many embedded images can require significant memory; size your worker accordingly. * **Resize threshold** — higher values reduce processing time at the cost of missed enhancements. * **Soft masks** (`useSoftMasked`) — improves quality but increases processing time. * **GPU** — multi-threading is not possible when using GPU features on a single GPU; scale with multiple instances/GPUs. * **Network paths** — avoid SMB / NFS where possible. * **`checkAdjacentImages`** — disable for complex PDFs with many small images. * **`streamReading`** — disable when processing PDFs with compressed image content. * **AI upscaling** — all modes except mode 6 significantly increase processing time. * **`maxFactor`** — limit to prevent excessive memory usage on large embedded images. * **`debug`** — disable in production. # Node.js Module VIESUS Node.js native module reference — installation, API, Docker, and performance tuning for in-process image enhancement. The VIESUS Node.js module is a native C++ addon that calls the VIESUS enhancement library **in-process** from a Node.js application. Enhancement runs on a worker thread pool, so it doesn't block the event loop. Ideal for SaaS platforms, REST APIs, and any JavaScript service that enhances images on upload. Linux only (Ubuntu 22.04+); GPU features require CUDA 12.6. For benchmarks and tuning see [Benchmarks](/operations/benchmarks).


Overview	Architectural overview of the native addon, threading model, and platform support.	Overview
Getting Started	Your first enhancement call: load the module, set up a GUID, enhance an image.	Getting Started
API Reference	Every exported function, parameter, return type, and event.	API Reference

# Overview The VIESUS Node.js native module integrates the VIESUS image enhancement engine into Node.js environments on Linux. Overview, architecture, and requirements. {% hint style="info" %} **Linux Only** The VIESUS Node.js module is available on **Linux only** (Ubuntu 22.04+). {% endhint %} The VIESUS Node.js module is a native C++ addon that integrates the VIESUS enhancement engine directly into Node.js processes. It is designed for web servers, REST APIs, and SaaS platforms that enhance images on upload without spawning external processes. *** ## How it works The module exposes a synchronous `Enhance()` call that runs inside **worker threads**. A static thread pool manages multiple workers in parallel; each worker holds a persistent VIESUS instance. The main Node.js event loop stays unblocked while images process concurrently. ```powershell Main Thread (event loop — non-blocking) └── StaticPool ├── Worker 1 → VIESUS instance → Enhance() ├── Worker 2 → VIESUS instance → Enhance() ├── Worker 3 → VIESUS instance → Enhance() └── Worker N → VIESUS instance → Enhance() ``` Scaling is straightforward: set the pool size to the number of CPU cores (for CPU processing) or the number of NVIDIA GPUs (for GPU-accelerated processing). *** ## Requirements See [System Requirements](/installation/requirements) for OS, Node.js, driver, and GPU requirements. *** ## Enhancement features All features in the [Configuration Reference](/configuration/parameter-reference) are available. The same `viesusini.json` used with the CLI works with the Node.js module. *** ## Performance For measured throughput (CPU-pool benchmarks, single-image latency) and the module's scaling characteristics, see [Benchmarks](/operations/benchmarks). # Getting Started A walkthrough of the worker.js and testbatch.js pattern for the VIESUS Node.js module — worker thread pool, batch processing, and GPU scaling. {% hint style="info" %} **Linux Only** The VIESUS Node.js module is available on **Linux only**. {% endhint %} The module uses a worker thread pool pattern. The main thread dispatches enhancement jobs to a pool of workers; each worker holds one persistent `MyViesusObject` instance initialized with your GUID. *** ## The two files you need ### `worker.js` Each worker thread initializes VIESUS once on startup and then processes jobs as they arrive: ```js const { parentPort, workerData } = require('worker_threads'); const viesus = require('viesus'); // Initialize once — workerData is the GUID passed from the pool const viesusObj = new viesus.MyViesusObject(workerData); parentPort.on('message', (job) => { const result = viesusObj.Enhance( job.fromPath, // input image — absolute path job.toPath, // output image — absolute path job.iniPath, // viesusini.json — absolute path job.resPath // result JSON — absolute path ); // result > 0: processing time in ms // result < 0: error code (see API Reference) parentPort.postMessage(result); }); ``` ### `testbatch.js` The main thread creates the pool and dispatches all images in a folder: ```js const { StaticPool } = require('node-worker-threads-pool'); const fs = require('fs'); const path = require('path'); const guid = 'YOUR-GUID-HERE'; const nGPUs = 0; // set to number of available NVIDIA GPUs; 0 = use CPU threads const nCPUThreads = Number(process.env.UV_THREADPOOL_SIZE); const nWorkers = nGPUs > 0 ? nGPUs : nCPUThreads; console.log(`Workers: ${nWorkers}, GUID: ${guid}`); const pool = new StaticPool({ size: nWorkers, task: './worker.js', workerData: guid }); async function enhance(fromPath, toPath, iniPath, resPath) { const result = await pool.exec({ fromPath, toPath, iniPath, resPath }); console.log(result > 0 ? `OK ${result}ms: ${fromPath}` : `ERR ${result}: ${fromPath}`); } const imageFolder = './in'; const outputFolder = './out'; const iniPath = path.resolve('./viesusini.json'); fs.readdir(imageFolder, (err, files) => { if (err) process.exit(1); files.forEach((file) => { const fromPath = path.resolve(imageFolder, file); const toPath = path.resolve(outputFolder, file.replace(/(\.[^.]*)?$/, '_viesus.jpg')); const resPath = path.resolve(outputFolder, file.replace(/(\.[^.]*)?$/, '_res.json')); fs.stat(fromPath, (e, stat) => { if (!e && stat.isFile()) enhance(fromPath, toPath, iniPath, resPath); }); }); }); ``` *** ## Running the batch ```bash mkdir in out # Copy test images to ./in/ export UV_THREADPOOL_SIZE=16 node testbatch.js ``` Each line of output is either `OK : ` (success) or `ERR

: ` (failure).

***

## Scaling to multiple GPUs

To use GPU acceleration, set `nGPUs` to the number of available NVIDIA GPUs. The pool is then limited to that count — one worker per GPU:

```js
const nGPUs = 2; // use 2 GPUs
```

One worker per GPU avoids VRAM contention. Running more workers than GPUs does not improve throughput and may cause OOM errors on the GPU.

***

## Express server integration example

This pattern integrates the pool into an Express upload endpoint:

```js
const express = require('express');
const multer = require('multer');
const { StaticPool } = require('node-worker-threads-pool');
const path = require('path');
const fs = require('fs');

const app = express();
const upload = multer({ dest: '/tmp/uploads/' });

const pool = new StaticPool({
  size: Number(process.env.UV_THREADPOOL_SIZE) || 4,
  task: './worker.js',
  workerData: process.env.VIESUS_GUID
});

app.post('/enhance', upload.single('image'), async (req, res) => {
  const fromPath = req.file.path;
  const toPath = fromPath + '_enhanced.jpg';
  const iniPath = path.resolve('./viesusini.json');
  const resPath = fromPath + '_result.json';

  try {
    const ms = await pool.exec({ fromPath, toPath, iniPath, resPath });
    if (ms < 0) return res.status(500).json({ error: ms });
    res.sendFile(toPath, () => {
      fs.unlink(fromPath, () => {});
      fs.unlink(toPath, () => {});
      fs.unlink(resPath, () => {});
    });
  } catch (err) {
    res.status(500).json({ error: err.message });
  }
});

app.listen(3000);
```

Pass the GUID as an environment variable — don't hardcode it:

```bash
VIESUS_GUID="your-guid" UV_THREADPOOL_SIZE=8 node server.js
```


# API Reference

Complete API reference for the VIESUS Node.js native module — MyViesusObject constructor, Enhance method, error codes, and result JSON.

{% hint style="info" %}
**Linux Only**

The VIESUS Node.js module is available on **Linux only**.
{% endhint %}

***

## Import

```js
const viesus = require('viesus');
```

***

## `new viesus.MyViesusObject(guid)`

Creates and initializes a VIESUS enhancer instance. Create one object per worker thread and **reuse it** across multiple `Enhance()` calls — initialization is expensive.

| Parameter | Type     | Description              |
| --------- | -------- | ------------------------ |
| `guid`    | `string` | Your VIESUS license GUID |

```js
const viesusObj = new viesus.MyViesusObject('4e8f35ab-7f72-4b1e-a1fd-2b5e9c58e9d3');
```

***

## `viesusObj.Enhance(fromPath, toPath, iniPath, resPath)`

Enhances a single image. **Synchronous** — must be called from a worker thread, not the main thread.

Parameter Type Description
fromPath string Absolute path to the input image
toPath string Absolute path for the enhanced output image
iniPath string Absolute path to the viesusini.json configuration file
resPath string Absolute path for the result JSON output file

**Returns:** `number`

* `> 0` — success; value is processing time in milliseconds
* `< 0` — error; see [error codes](#error-codes)

```js
const result = viesusObj.Enhance(fromPath, toPath, iniPath, resPath);
if (result > 0) {
  console.log(`Enhanced in ${result}ms`);
} else {
  console.error(`Error: ${result}`);
}
```

***

## Error codes

Code Description
-1 Init failed
-2 GUID wrong
-3 Internal error
-4 Loading image not possible
-5 Can't open file
-6 File not found
-7 File is empty
-8 Memory open internal error
-9 Enhancement failed — contact info@viesus.com
-10 Parameter file not found
-11 Parameter file empty
-12 Output format not supported
-13 Error writing result file
-126 Enhancement failed — image was already enhanced
-378 Wrong GUID
< -18 Internal error — contact info@viesus.com

***

## Result JSON

When `WriteResultFiles: 1` is set in `viesusini.json`, a JSON file is written to `resPath` after each enhancement with per-image processing details:

```json
{
  "brightCorrStrength": 0.011,
  "colorCorrStrength": 0.083,
  "contrCorrStrength": 0.0,
  "fdApplied": 1,
  "ggaApplied": 0,
  "globShpApplied": 0,
  "glowStrength": 0.0,
  "ieApplied": 1,
  "isArtificial": 0,
  "isMonochrome": 0,
  "locShpApplied": 1,
  "noiseStrength": 0.0,
  "nrApplied": 0,
  "rerApplied": 1,
  "rszApplied": 1,
  "rszSRApplied": 0,
  "arApplied": 0,
  "bgApplied": 0,
  "staApplied": 0
}
```

Field Type Description
brightCorrStrength float Applied brightness correction strength
colorCorrStrength float Applied color correction strength
fdApplied int 1 if face detection ran
ieApplied int 1 if image enhancement ran
isArtificial int 1 if image was classified as artificial/synthetic
isMonochrome int 1 if image was detected as monochrome
locShpApplied int 1 if local sharpening was applied
rszApplied int 1 if resizing was applied
rszSRApplied int 1 if AI upscaling was used for resize
arApplied int 1 if artifact removal was applied
bgApplied int 1 if background handling was applied

***

## Thread pool pattern

The recommended production pattern uses `node-worker-threads-pool`:

```js
// worker.js
const { parentPort, workerData } = require('worker_threads');
const viesus = require('viesus');

const viesusObj = new viesus.MyViesusObject(workerData);

parentPort.on('message', (job) => {
  const result = viesusObj.Enhance(job.fromPath, job.toPath, job.iniPath, job.resPath);
  parentPort.postMessage(result);
});
```

```js
// main.js
const { StaticPool } = require('node-worker-threads-pool');

const pool = new StaticPool({
  size: Number(process.env.UV_THREADPOOL_SIZE),
  task: './worker.js',
  workerData: 'YOUR-GUID-HERE'
});

async function enhanceImage(fromPath, toPath, iniPath, resPath) {
  const result = await pool.exec({ fromPath, toPath, iniPath, resPath });
  if (result < 0) throw new Error(`VIESUS error: ${result}`);
  return result;
}
```

See [Getting Started](/reference/node.js-module/getting-started) for the complete example.


# Docker

Run VIESUS in GPU-enabled Docker containers — guides for the CLI and the Node.js module.

Run VIESUS in GPU-enabled containers. Both the CLI and the Node.js module install the VIESUS `.deb` packages inside the image and pass through an NVIDIA GPU via the NVIDIA Container Toolkit (`--gpus all`).

Docker for CLI Build a GPU-enabled image for the viesus CLI and run batch jobs in a container. Docker for CLI
Docker for Node.js Containerize the Node.js module for a request-driven enhancement service. Docker for Node.js

For deployment concerns common to both, see [Docker Production Deployment](/use-cases/docker-production).


# Docker for CLI

Step-by-step guide to running the VIESUS CLI in a GPU-enabled Ubuntu Docker container with NVIDIA GPU support.

This guide walks through building a minimal Ubuntu-based Docker image with the VIESUS CLI and NVIDIA GPU support. Use it as a starting point — not a complete production setup.

**Prerequisites:**

* Ubuntu 22.04 host
* NVIDIA driver with CUDA 12.6 support or newer (`nvidia-smi` must work)
* Docker installed
* VIESUS `.deb` package downloaded from [transfer.viesus.com](https://transfer.viesus.com)

***

{% stepper %}
{% step %}

## Install Docker

```bash
sudo apt-get update && sudo apt-get upgrade -y
sudo apt-get install -y apt-transport-https ca-certificates curl software-properties-common
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt-get update
sudo apt-get install -y docker-ce

# Allow running Docker without sudo
sudo usermod -aG docker $USER
su - $USER
```

Verify:

```bash
docker -v
```

{% endstep %}

{% step %}

## Install NVIDIA Container Toolkit

Follow the [official NVIDIA guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html).

Verify GPU access in Docker:

```bash
docker run -it --gpus all nvidia/cuda:12.6.0-runtime-ubuntu22.04 nvidia-smi
```

{% hint style="info" %}
Use the `runtime` image variant, not `base`. The base image does not include all required CUDA runtime libraries.
{% endhint %}
{% endstep %}

{% step %}

## Prepare the build context

```bash
mkdir viesusdocker
cd viesusdocker

# Copy the VIESUS deb package into the build context
cp ~/viesus__amd64.deb .
```

{% endstep %}

{% step %}

## Create the Dockerfile

```dockerfile
FROM nvidia/cuda:12.6.0-runtime-ubuntu22.04

COPY ./viesus__amd64.deb /

ENV DEBIAN_FRONTEND=noninteractive
ENV TZ=Etc/UTC

RUN apt-get update && apt-get install -y --no-install-recommends wget
RUN dpkg -i /viesus__amd64.deb
RUN apt-get install -y libnuma-dev
```

{% hint style="info" %}
`libnuma-dev` is required for the VIESUS library on Ubuntu 22.04.
{% endhint %}

{% hint style="info" %}
The `nvidia/cuda` base image tag (`12.6.0-runtime-ubuntu22.04`) must match your host NVIDIA driver. Check the [NVIDIA Container Registry](https://catalog.ngc.nvidia.com/orgs/nvidia/containers/cuda) for available tags and replace `12.6.0` as needed.
{% endhint %}
{% endstep %}

{% step %}

## Build the image

```bash
docker build -t viesusdocker .
```

{% endstep %}

{% step %}

## Prepare images and configuration

Create a shared folder on the host that will be mounted into the container:

```bash
mkdir -p ~/testimages

# Create an image list using container-side paths
cat > ~/testimages/images.lst << 'EOF'
/mnt/mydata/image1.jpg
/mnt/mydata/image2.jpg
/mnt/mydata/image3.jpg
EOF
```

Create `~/testimages/viesusini.json` with your enhancement configuration. Example for 4× AI upscaling with Face Reconstruction:

```json
{
  "Config": {
    "Enhancemode": 1,
    "NoiseRedMode": 1,
    "FDmode": 1,
    "FRmode": 1,
    "ARmode": 1,
    "SHPmode": 1
  },
  "Resize": {
    "ResizeOn": 1,
    "ResizeMode": 5,
    "ResizeFactor": 4.0,
    "SupResThresh": 1.0,
    "ResizeFacDetMode": 0
  },
  "Other": {
    "JpegComprQuality": 95
  }
}
```

{% endstep %}

{% step %}

## Run the CLI

**Process a list of images:**

```bash
docker run \
  --mount "type=bind,source=$HOME/testimages,target=/mnt/mydata" \
  --rm --gpus all viesusdocker \
  /usr/local/viesus/viesus \
  -g "YOUR-GUID-HERE" \
  -p /mnt/mydata/viesusini.json \
  -s \
  -l /mnt/mydata/images.lst
```

**Process a single image:**

```bash
docker run \
  --mount "type=bind,source=$HOME/testimages,target=/mnt/mydata" \
  --rm --gpus all viesusdocker \
  /usr/local/viesus/viesus \
  -g "YOUR-GUID-HERE" \
  -p /mnt/mydata/viesusini.json \
  -s \
  -f /mnt/mydata/image1.jpg
```

**Open a shell for debugging:**

```bash
docker run -it --gpus all viesusdocker bash
```

{% endstep %}
{% endstepper %}

***

## Production considerations

Concern Recommendation
GUID security Pass the GUID via an environment variable or Docker secret rather than hardcoding it in scripts
Output volume Mount a dedicated output volume; don't write to the same path as input
Parallelism Scale by running multiple containers (or instances) rather than more threads per instance
Image list generation Generate the image list outside the container and mount it in; avoid running find inside the container
Restart policy Use --restart unless-stopped for long-running hotfolder containers
Log collection Pipe stdout/stderr to your log aggregator; the CLI writes processing results to .res files


# Docker for Node.js

Run the VIESUS Node.js module in a GPU-enabled Docker container. Dockerfile, build, and run instructions for Linux production deployments.

{% hint style="info" %}
**Linux Only**

The VIESUS Node.js module is available on **Linux only**.
{% endhint %}

Containerizing the Node.js module follows the same foundation as the CLI Docker setup — the VIESUS `.deb` packages are installed inside the container, then the npm module is linked from the installed location.

***

## Prerequisites

* Docker Engine installed on the host
* NVIDIA Container Toolkit installed (for GPU support)
* VIESUS `.deb` packages (`.deb` files must be in your build context)

If you do not already have the NVIDIA Container Toolkit:

```bash
# Add NVIDIA Container Toolkit repository
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker
```

***

## Build context

Prepare the directory you'll build from:

```powershell
viesus-node-docker/
├── Dockerfile
├── viesus-redist__amd64.deb
├── viesus__amd64.deb
├── viesus-license__amd64.deb
├── package.json
├── server.js            # or your application entry point
├── worker.js
└── viesusini.json
```

***

## Dockerfile

```dockerfile
FROM nvidia/cuda:12.6.0-runtime-ubuntu22.04

ENV DEBIAN_FRONTEND=noninteractive

# System dependencies
RUN apt-get update && apt-get install -y \
    curl \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# Install VIESUS packages
COPY viesus-redist__amd64.deb \
     viesus__amd64.deb \
     viesus-license__amd64.deb /tmp/
RUN dpkg -i /tmp/viesus-redist__amd64.deb \
            /tmp/viesus__amd64.deb \
            /tmp/viesus-license__amd64.deb && \
    apt-get install -f -y && \
    rm /tmp/*.deb

# Install Node.js 18
RUN curl -sL https://deb.nodesource.com/setup_18.x | bash - && \
    apt-get install -y nodejs && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /app

# Install npm dependencies (including viesus native module)
COPY package.json ./
RUN npm install /usr/local/viesus/node-viesus && \
    npm install node-worker-threads-pool --save

# Copy application files
COPY worker.js server.js viesusini.json ./

EXPOSE 3000

ENV UV_THREADPOOL_SIZE=16

CMD ["node", "server.js"]
```

{% hint style="info" %}
The `nvidia/cuda` base image tag (`12.6.0-runtime-ubuntu22.04`) must match your host NVIDIA driver. Check the [NVIDIA Container Registry](https://catalog.ngc.nvidia.com/orgs/nvidia/containers/cuda) for available tags and replace `12.6.0` as needed.
{% endhint %}

***

## Build the image

```bash
docker build -t viesus-node:latest .
```

***

## Run the container

### CPU mode

```bash
docker run -d \
  --name viesus-node \
  -p 3000:3000 \
  -e VIESUS_GUID="your-guid-here" \
  -e UV_THREADPOOL_SIZE=16 \
  viesus-node:latest
```

### GPU mode

```bash
docker run -d \
  --name viesus-node \
  --gpus all \
  -p 3000:3000 \
  -e VIESUS_GUID="your-guid-here" \
  -e UV_THREADPOOL_SIZE=4 \
  viesus-node:latest
```

When using GPUs, set `UV_THREADPOOL_SIZE` to the number of GPUs, not the number of CPU cores. See [GPU Scaling](/reference/node.js-module/getting-started#scaling-to-multiple-gpus).

***

## Passing the GUID securely

Never hardcode the GUID in the Dockerfile or application code. Pass it at runtime:

```bash
# Directly
docker run -e VIESUS_GUID="your-guid-here" ...

# From an env file
docker run --env-file .env ...

# Docker secret (Swarm/Compose)
docker secret create viesus_guid ./guid.txt
```

Read the GUID in your application:

```js
const pool = new StaticPool({
  size: Number(process.env.UV_THREADPOOL_SIZE) || 4,
  task: './worker.js',
  workerData: process.env.VIESUS_GUID
});
```

***

## Docker Compose example

```yaml
version: '3.8'

services:
  viesus-node:
    build: .
    ports:
      - "3000:3000"
    environment:
      - VIESUS_GUID=${VIESUS_GUID}
      - UV_THREADPOOL_SIZE=16
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    restart: unless-stopped
```

Run with:

```bash
VIESUS_GUID="your-guid-here" docker-compose up -d
```

***

## Production considerations

Topic Recommendation
Image size Use multi-stage builds to reduce final image size; the CUDA runtime base is large
GUID security Pass via environment variable or secret manager — never bake into the image
Graceful shutdown Handle SIGTERM to allow in-flight requests to complete before the pool closes
Health check Add a lightweight GET /health endpoint that returns 200; use it for readiness probes
Logging Stream stdout/stderr — Docker captures it; ship to your log aggregator
GPU reservation Use --gpus all or specify by device ID if only some GPUs should be used


# Cloud API

VIESUS Cloud GraphQL API reference — authentication, uploading, image and PDF enhancement, credits, and webhooks.

The VIESUS Cloud API is a hosted GraphQL service for image and PDF enhancement. No server to manage, no GUID to bind, no GPU to procure — upload, enhance, download. Billed per image via a credit system, with a free tier for evaluation.

Use the Cloud API when you don't want to operate your own infrastructure, when you need on-demand AI upscaling without a local GPU, or to add VIESUS to a frontend that already calls other cloud APIs.

Overview What the Cloud API offers, when to use it vs on-premise, and the GraphQL endpoint. Overview
Authentication API keys, header conventions, and how to manage authentication for production. Authentication
Uploading Multipart upload, file size limits, supported formats, and signed URLs. Uploading
Enhance Images The image enhancement mutation: parameters, options, response shape, async behavior. Enhance Images
Enhance PDFs PDF enhancement endpoint, page selection, and result retrieval. Enhance PDFs
Credits How credits are consumed, free tier limits, and how to top up. Credits
Webhooks Async notification on enhancement completion — payload format, retries, and signing. Webhooks


# Overview

VIESUS Cloud is a managed GraphQL API for image and PDF enhancement. No infrastructure required — upload, enhance, retrieve.

VIESUS Cloud is a fully managed API that gives you access to the complete VIESUS enhancement engine without installing or operating any infrastructure. Upload images or PDFs, trigger enhancements, and retrieve results — pay only for what you process.

***

## Engine version

VIESUS Cloud currently runs **VIESUS 12**.

This version applies to the managed enhancement engine behind the Cloud API and Webapp. Platform updates are rolled out on the server side, so you do not install or upgrade the engine yourself.

***

## API endpoint

All requests go to a single GraphQL endpoint:

```powershell
https://api.viesus.cloud/graphql
```

Requests are standard HTTP POST with a JSON body. Any GraphQL client library or plain `fetch`/`curl` works.

| Language | Recommended library        |
| -------- | -------------------------- |
| Node.js  | `graphql-request`          |
| Python   | `gql`                      |
| PHP      | `webonyx/graphql-php`      |
| Go       | `hasura/go-graphql-client` |

### GraphQL Playground

Explore the full schema and run queries interactively: 

Add your `x-api-key` header and run any mutation or query directly from the browser. The schema browser shows all available enum values and input types.

***

## How it works

Every integration follows five steps:

```powershell
1. Authenticate  →  x-api-key header on every request
2. Upload        →  from URL or via signed upload URL
3. Enhance       →  createEnhancedImage mutation
4. Poll / webhook →  check status or receive push notification
5. Retrieve      →  download from fullUrl
```

The same upload can be enhanced multiple times with different parameters — useful for A/B testing configurations or generating multiple output variants.

***

## Supported file types

Format MIME type Notes
JPEG image/jpeg 
PNG image/png 
TIFF image/tiff 
HEIC image/heic Currently converted to JPEG after processing — this will change in a future version
WebP image/webp Currently converted to JPEG after processing — this will change in a future version
PDF application/pdf Requires analysis phase before enhancement

**File size limits:**

| Type      | Minimum | Maximum  |
| --------- | ------- | -------- |
| Images    | 20 KB   | 50 MB    |
| PDF files | 20 KB   | 1,000 MB |

***

## Use cases

Scenario Approach
SaaS product — enhance on upload Signed upload URL → webhook on completion
Batch from existing CDN Upload from URL in a loop → poll or webhook
PDF print workflow Upload PDF → wait for analysis → enhance
A/B test enhancement settings One upload → multiple createEnhancedImage calls
One-off manual enhancement Dashboard UI (no API required)

***

## Quick example

```bash
# 1. Upload from URL
UPLOAD_ID=$(curl -s -X POST https://api.viesus.cloud/graphql \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR-API-KEY" \
  -d '{"query":"mutation { createUploadFromUrl(input: { url: \"https://example.com/photo.jpg\" }) { id } }"}' \
  | jq -r '.data.createUploadFromUrl.id')

# 2. Enhance
ENHANCEMENT_ID=$(curl -s -X POST https://api.viesus.cloud/graphql \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR-API-KEY" \
  -d "{\"query\":\"mutation { createEnhancedImage(uploadId: \\\"$UPLOAD_ID\\\", input: { mode: ENHANCE }) { id status } }\"}" \
  | jq -r '.data.createEnhancedImage.id')

# 3. Check status
curl -s -X POST https://api.viesus.cloud/graphql \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR-API-KEY" \
  -d "{\"query\":\"query { enhancedImage(id: \\\"$ENHANCEMENT_ID\\\") { status fullUrl } }\"}"
```


# Authentication

Authenticate VIESUS Cloud API requests using the x-api-key header. Creating and managing API keys.

VIESUS Cloud authenticates every request using an API key passed as an HTTP header. There is no session, no OAuth flow, and no token expiry — just a static key on every request.

***

## Header format

```powershell
x-api-key: 
```

Include this header on every request to the GraphQL endpoint.

***

## Examples

**curl:**

```bash
curl -X POST https://api.viesus.cloud/graphql \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{"query": "query { credits { remainingCreditsThisPeriod } }"}'
```

**Node.js (`graphql-request`):**

```js
import { GraphQLClient } from 'graphql-request';

const client = new GraphQLClient('https://api.viesus.cloud/graphql', {
  headers: {
    'x-api-key': process.env.VIESUS_API_KEY,
  },
});
```

**Python (`gql`):**

```python
from gql import gql, Client
from gql.transport.requests import RequestsHTTPTransport

transport = RequestsHTTPTransport(
    url='https://api.viesus.cloud/graphql',
    headers={'x-api-key': 'your-api-key-here'},
)
client = Client(transport=transport, fetch_schema_from_transport=True)
```

**PHP (`GuzzleHttp`):**

```php
$client = new \GuzzleHttp\Client([
    'base_uri' => 'https://api.viesus.cloud/graphql',
    'headers' => [
        'x-api-key' => 'your-api-key-here',
        'Content-Type' => 'application/json',
    ],
]);
```

***

## Creating an API key

API keys are managed in the dashboard:

→ ****

{% stepper %}
{% step %}
Log in to your account.
{% endstep %}

{% step %}
Navigate to **API Keys**.
{% endstep %}

{% step %}
Click **Create new key** and give it a descriptive name.
{% endstep %}

{% step %}
Copy and store the key securely — it is shown **only once**.
{% endstep %}
{% endstepper %}

If you lose the key, delete it and create a new one.

***

## Best practices

**Never hardcode the key in source code.** Pass it through an environment variable:

```bash
VIESUS_API_KEY="your-key-here" node server.js
```

```js
const apiKey = process.env.VIESUS_API_KEY;
if (!apiKey) throw new Error('VIESUS_API_KEY is not set');
```

**Rotate keys when team members leave** or if a key may have been exposed. Create a new key first, update all integrations, then delete the old key.

**Use separate keys per environment** (development, staging, production). This limits blast radius if a key leaks and makes it easier to track usage by environment.

***

## Verifying your key

Query the credit balance — if this returns data, your key is valid:

```graphql
query {
  credits {
    remainingCreditsThisPeriod
    usedCreditsThisPeriod
    periodStart
    periodEnd
  }
}
```

A missing or invalid key returns an authentication error in the GraphQL response.


# Uploading

Upload images and PDFs to VIESUS Cloud via URL or signed upload URL. Response fields, retention, and deletion.

Every enhancement starts with an upload. The upload creates a persistent file record that you reference by `id` in subsequent enhancement requests.

***

## Which method to use

| Your file is...                 | Method                                          |
| ------------------------------- | ----------------------------------------------- |
| At a reachable public URL       | [Upload from URL](#upload-from-a-url) — simpler |
| On your server or local machine | [Signed upload URL](#upload-with-a-signed-url)  |

***

## Upload from a URL

The simplest method. VIESUS Cloud fetches the file directly from the URL you provide.

```graphql
mutation {
  createUploadFromUrl(
    input: {
      url: "https://www.example.com/photo.jpg"
    }
  ) {
    id
    status
    filesize
    mimetype
    extension
    originalFilename
    filename
    width
    height
    url
    startedAt
    finishedAt
    duration
  }
}
```

Save the returned `id` — you need it to trigger enhancements.

**curl example:**

```bash
curl -X POST https://api.viesus.cloud/graphql \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR-API-KEY" \
  -d '{
    "query": "mutation { createUploadFromUrl(input: { url: \"https://example.com/photo.jpg\" }) { id status } }"
  }'
```

***

## Upload with a signed URL

For files on your server, local machine, or user uploads that go directly from the browser to VIESUS Cloud storage. This is a three-step process.

{% stepper %}
{% step %}

#### Request a signed URL

```graphql
mutation {
  createSignedUploadUrl(
    input: {
      filename: "photo.jpg"
      filesize: 2048000
      mimetype: "image/jpeg"
    }
  ) {
    uploadId
    uploadUrl
  }
}
```

{% hint style="danger" %}
`filesize` and `mimetype` must match the actual file. Incorrect values cause the upload to fail at the final step.
{% endhint %}
{% endstep %}

{% step %}

#### PUT the file to the signed URL

Use the `uploadUrl` from the previous step to PUT the file directly to storage:

**Node.js:**

```js
const fs = require('fs');

const filePath = './photo.jpg';
const fileBuffer = fs.readFileSync(filePath);
const stats = fs.statSync(filePath);

await fetch(uploadUrl, {
  method: 'PUT',
  body: fileBuffer,
  headers: {
    'Content-Type': 'image/jpeg',
    'Content-Length': stats.size.toString(),
  },
});
```

**Browser (file input):**

```js
async function putFile(uploadUrl, file) {
  await fetch(uploadUrl, {
    method: 'PUT',
    body: await file.arrayBuffer(),
    headers: {
      'Content-Type': file.type,
    },
  });
}
```

**curl:**

```bash
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: image/jpeg" \
  --data-binary @photo.jpg
```

{% endstep %}

{% step %}

#### Complete the upload

Finalize using the `uploadId` from the first step:

```graphql
mutation {
  completeSignedUpload(id: "uploadId") {
    id
    status
    filesize
    mimetype
    width
    height
    url
    startedAt
    finishedAt
    duration
  }
}
```

The returned `id` is the upload ID for all subsequent enhancement requests.
{% endstep %}
{% endstepper %}

***

## Upload response fields

Field Description
id Upload identifier — required for enhancement mutations
status Upload state
filesize File size in bytes
mimetype Detected MIME type
extension File extension
originalFilename Filename as uploaded
filename Storage filename
width / height Image dimensions in pixels (0 for PDFs)
url URL to access the original uploaded file
startedAt / finishedAt Upload timestamps (ISO 8601)
duration Upload processing time in milliseconds

***

## Upload retention

Uploads are stored for **30 days** by default, then automatically deleted. To change the default retention for new uploads:

```graphql
mutation {
  updateFileRetention(days: 7) {
    uploadRetentionDays
  }
}
```

This setting applies to uploads made after the change — existing uploads keep their original retention.

To delete an upload immediately:

```graphql
mutation {
  deleteUploads(ids: ["upload-id-1", "upload-id-2"]) {
    deletedUploadIds
  }
}
```

***

## Multiple enhancements from one upload

The same upload can be enhanced multiple times with different parameters. You do not need to re-upload the file:

```graphql
mutation EnhanceA {
  createEnhancedImage(uploadId: "upload-id", input: { mode: ENHANCE }) {
    id status
  }
}

mutation EnhanceB {
  createEnhancedImage(uploadId: "upload-id", input: { mode: ENHANCE, upscalingFactor: X2 }) {
    id status
  }
}
```

This is useful for generating multiple output variants (e.g., with and without upscaling) without paying upload costs twice.


# Enhance Images

Trigger image enhancements with createEnhancedImage. Parameters, status, AI upscaling limits, and polling vs webhooks.

Once an image is uploaded, trigger enhancement with the `createEnhancedImage` mutation. Processing takes **2–180 seconds** depending on features and server load.

***

## Create an enhancement

```graphql
mutation {
  createEnhancedImage(
    uploadId: "your-upload-id"
    input: {
      mode: ENHANCE
      noiseReductionProfilingMode: AUTO
      noiseReductionProfilingStrength: 0.5
      artifactsDetectionRemoval: AUTO_AI
      enhanceFaceDetails: ENHANCE
      upscalingFactor: X2
    }
  ) {
    id
    status
    fullUrl
    filename
    viesusDuration
  }
}
```

Save the returned `id` — you need it to check status or retrieve the result later.

***

## Input parameters

| Parameter                                   | Type                                                 | Description                               |
| ------------------------------------------- | ---------------------------------------------------- | ----------------------------------------- |
| `mode`                                      | `EnhancedImageEnhancementMode`                       | Overall enhancement mode                  |
| `preset`                                    | `EnhancedImageParametersPreset`                      | Pre-configured enhancement profile        |
| `noiseReductionProfilingMode`               | `EnhancedImageParametersNoiseReductionProfilingMode` | Noise reduction mode                      |
| `noiseReductionProfilingStrength`           | `Decimal`                                            | Noise reduction strength (`0.0`–`1.0`)    |
| `noiseReductionProfilingMonochromeStrength` | `Decimal`                                            | Monochrome noise reduction (`0.0`–`1.0`)  |
| `artifactsDetectionRemoval`                 | `EnhancedImageParametersArtifactsDetectionRemoval`   | JPEG artifact removal mode                |
| `enhanceFaceDetails`                        | `EnhancedImageParametersEnhanceFaceDetails`          | Face detail enhancement                   |
| `redEyeCorrectionsMode`                     | `EnhancedImageParametersRedEyeCorrectionsMode`       | Red-eye correction mode                   |
| `redEyeCorrectionsStrength`                 | `Decimal`                                            | Red-eye correction strength (`0.0`–`1.0`) |
| `redEyeCorrectionsEyeStrength`              | `Decimal`                                            | Eye correction strength (`0.0`–`1.0`)     |
| `noiseAdditionProfilingStrength`            | `Decimal`                                            | Grain addition strength (`0.0`–`1.0`)     |
| `upscalingFactor`                           | `EnhancedImageParametersUpscalingFactor`             | AI upscaling factor (`X2`, `X4`, etc.)    |
| `upscalingCustomWidth`                      | `Int`                                                | Target output width in pixels             |
| `upscalingCustomDPI`                        | `Int`                                                | Target output DPI                         |
| `backgroundRemovalMode`                     | `EnhancedImageParametersPortraitBackgroundMode`      | Background removal/replacement            |
| `backgroundRemovalBlur`                     | `Decimal`                                            | Background blur strength (`0.0`–`1.0`)    |
| `backgroundRemovalReplaceImageUrl`          | `String`                                             | URL of a replacement background image     |
| `customColorConfig`                         | `CustomColorConfigInput`                             | Manual color adjustments                  |

For all enum values, open the schema browser at ****.

***

## AI upscaling limits

| Constraint                | Value                       |
| ------------------------- | --------------------------- |
| Maximum input dimension   | 3,000 px (width or height)  |
| Maximum enlargement ratio | 4×                          |
| Maximum output dimension  | 11,996 px (width or height) |

AI upscaling costs **4 credits** per image. See [Credits](/reference/cloud-api/credits).

***

## Check enhancement status

```graphql
query {
  enhancedImage(id: "enhancement-id") {
    id
    status
    fullUrl
    filename
    viesusDuration
    errorCode
  }
}
```

| Status     | Meaning                                   |
| ---------- | ----------------------------------------- |
| `QUEUED`   | Waiting for a processing slot             |
| `FINISHED` | Complete — `fullUrl` is ready to download |
| `ERROR`    | Failed — inspect `errorCode`              |

When `status` is `FINISHED`, the enhanced image is available at `fullUrl`. The URL is valid for the duration of the upload's retention period.

***

## All enhancements for an upload

Multiple enhancements can share a single upload (different parameters, different output variants):

```graphql
query {
  upload(id: "upload-id") {
    id
    status
    EnhancedImages {
      id
      status
      fullUrl
      filename
      viesusDuration
      errorCode
    }
  }
}
```

***

## Polling vs webhooks

**Polling** is straightforward but wastes requests when processing is slow:

```js
async function waitForEnhancement(client, id, intervalMs = 3000) {
  while (true) {
    const { enhancedImage } = await client.request(STATUS_QUERY, { id });
    if (enhancedImage.status === 'FINISHED') return enhancedImage.fullUrl;
    if (enhancedImage.status === 'ERROR') throw new Error(`Enhancement failed: ${enhancedImage.errorCode}`);
    await new Promise(r => setTimeout(r, intervalMs));
  }
}
```

**Webhooks** are recommended for production — your server is notified when the result is ready. See [Webhooks](/reference/cloud-api/webhooks).

***

## Minimal enhancement example (Node.js)

```js
import { GraphQLClient, gql } from 'graphql-request';

const client = new GraphQLClient('https://api.viesus.cloud/graphql', {
  headers: { 'x-api-key': process.env.VIESUS_API_KEY },
});

const UPLOAD = gql`
  mutation ($url: String!) {
    createUploadFromUrl(input: { url: $url }) { id }
  }
`;

const ENHANCE = gql`
  mutation ($uploadId: ID!) {
    createEnhancedImage(uploadId: $uploadId, input: { mode: ENHANCE }) { id status }
  }
`;

const STATUS = gql`
  query ($id: ID!) {
    enhancedImage(id: $id) { status fullUrl errorCode }
  }
`;

async function enhance(imageUrl) {
  const { createUploadFromUrl } = await client.request(UPLOAD, { url: imageUrl });
  const { createEnhancedImage } = await client.request(ENHANCE, { uploadId: createUploadFromUrl.id });

  let result;
  do {
    await new Promise(r => setTimeout(r, 3000));
    result = (await client.request(STATUS, { id: createEnhancedImage.id })).enhancedImage;
  } while (result.status === 'QUEUED');

  if (result.status === 'ERROR') throw new Error(`Error: ${result.errorCode}`);
  return result.fullUrl;
}
```


# Enhance PDFs

Enhance PDFs via VIESUS Cloud. Analysis phase, enhancement parameters, DPI limits by subscription tier, and webhook events.

PDF enhancement works differently from image enhancement. Before any enhancement can be triggered, the PDF must go through an **analysis phase** that identifies all embedded images and calculates the credit cost. Analysis starts automatically after upload.

***

{% stepper %}
{% step %}

## Upload the PDF

Upload using either method from Uploading. Save the returned `id`.

```graphql
mutation {
  createUploadFromUrl(
    input: { url: "https://example.com/photobook.pdf" }
  ) {
    id
    status
  }
}
```

Analysis begins automatically after the upload completes.
{% endstep %}

{% step %}

## Wait for analysis

Query the upload to check analysis progress:

```graphql
query {
  upload(id: "your-upload-id") {
    id
    subStatus
    metadata
  }
}
```

**Analysis status values**

| `subStatus`                      | Meaning               | Action                           |
| -------------------------------- | --------------------- | -------------------------------- |
| `METADATA_ANALYZING`             | Analysis in progress  | Wait or use a webhook            |
| `METADATA_ANALYZED_SUCCESSFULLY` | Ready for enhancement | Proceed to the next step         |
| `METADATA_ANALYZED_FAILED`       | Analysis failed       | Retry with `analyzePdf` mutation |

**Analysis results**

When analysis succeeds, the `metadata` field contains:

* Total image count in the PDF
* Number of images eligible for color enhancement
* Number of images eligible for resizing/upscaling
* Estimated credit cost for different enhancement combinations

Review the credit estimate before triggering enhancement — especially for large PDFs.

{% hint style="info" %}
**Does analysis distinguish customer photos from embedded artwork?**

No. Analysis doesn't classify embedded raster images by content type. It identifies every raster image in the PDF and reports eligibility based on technical criteria (such as image size and color variation) — not on whether the image is a customer photo or design artwork. There's currently no way to flag individual images for exclusion; enhancement applies to all images that meet the eligibility criteria. If a PDF mixes customer photos with raster artwork you don't want enhanced, review the eligible-image counts from analysis before calling `createEnhancedImage`.
{% endhint %}

**Re-trigger analysis (on failure)**

```graphql
mutation {
  analyzePdf(uploadId: "your-upload-id") {
    success
  }
}
```

Expected response when the re-analysis request is successfully queued:

```json
{ "success": true }
```

If analysis fails repeatedly after multiple re-analysis attempts, this may indicate file format incompatibility, corrupted document content, or system processing limitations. Contact [VIESUS technical support](https://www.viesus.cloud) with your upload ID and file details for further investigation.
{% endstep %}

{% step %}

## Enhance the PDF

Once `subStatus` is `METADATA_ANALYZED_SUCCESSFULLY`:

```graphql
mutation {
  createEnhancedImage(
    uploadId: "your-upload-id"
    input: {
      targetResolution: 300
      upscalingThreshold: 1.2
    }
  ) {
    id
    status
    fullUrl
    filename
    viesusDuration
  }
}
```

**Parameters for PDF enhancement**

| Parameter            | Type                     | Description                                                                                                                            |
| -------------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `targetResolution`   | `Decimal`                | Target output DPI for embedded images                                                                                                  |
| `upscalingThreshold` | `Decimal`                | Minimum scale factor required before upscaling is applied to an image; `1.2` = only upscale images that need more than 20% enlargement |
| `customColorConfig`  | `CustomColorConfigInput` | Manual color adjustments                                                                                                               |

{% hint style="info" %}
PDF enhancement supports only these three parameters. The full image enhancement parameter set (noise reduction, face details, etc.) does not apply to PDFs.
{% endhint %}
{% endstep %}

{% step %}

## Retrieve the enhanced PDF

Check status using the `id` from the previous step:

```graphql
query {
  enhancedImage(id: "enhancement-id") {
    id
    status
    fullUrl
    filename
    viesusDuration
    errorCode
  }
}
```

When `status` is `FINISHED`, the enhanced PDF is available at `fullUrl`.
{% endstep %}
{% endstepper %}

***

## Upscaling limits by subscription

PDF enhancement output resolution is capped by subscription tier:

| Subscription | Maximum output resolution |
| ------------ | ------------------------- |
| Free         | 300 DPI                   |
| Basic        | 600 DPI                   |
| Business     | 1,200 DPI                 |

***

## Webhook events for PDFs

Rather than polling, use webhooks to receive push notifications for both events:

**Analysis complete** — `upload.sub_status_update`:

```json
{
  "id": "eventId",
  "event": "upload.sub_status_update",
  "data": {
    "id": "uploadId",
    "status": "UPLOAD_FINISHED",
    "subStatus": "METADATA_ANALYZED_SUCCESSFULLY",
    "metadata": {
      "statistics": {},
      "totalCredits": 78
    }
  },
  "created": "2025-05-15T14:12:37.501Z"
}
```

**Enhancement complete** — same event structure with `status: FINISHED` on the `enhancedImage`.

See Webhooks for setup and signature verification.

***

## End-to-end Node.js example

```js
import { GraphQLClient, gql } from 'graphql-request';

const client = new GraphQLClient('https://api.viesus.cloud/graphql', {
  headers: { 'x-api-key': process.env.VIESUS_API_KEY },
});

async function enhancePdf(pdfUrl) {
  // Upload
  const { createUploadFromUrl } = await client.request(gql`
    mutation { createUploadFromUrl(input: { url: "${pdfUrl}" }) { id } }
  `);
  const uploadId = createUploadFromUrl.id;

  // Wait for analysis
  let upload;
  do {
    await new Promise(r => setTimeout(r, 5000));
    upload = (await client.request(gql`
      query { upload(id: "${uploadId}") { subStatus metadata } }
    `)).upload;
  } while (upload.subStatus === 'METADATA_ANALYZING');

  if (upload.subStatus !== 'METADATA_ANALYZED_SUCCESSFULLY') {
    throw new Error(`Analysis failed: ${upload.subStatus}`);
  }

  console.log('Estimated credits:', JSON.parse(upload.metadata).totalCredits);

  // Enhance
  const { createEnhancedImage } = await client.request(gql`
    mutation {
      createEnhancedImage(
        uploadId: "${uploadId}",
        input: { targetResolution: 300, upscalingThreshold: 1.2 }
      ) { id }
    }
  `);

  // Wait for completion
  let result;
  do {
    await new Promise(r => setTimeout(r, 10000));
    result = (await client.request(gql`
      query { enhancedImage(id: "${createEnhancedImage.id}") { status fullUrl errorCode } }
    `)).enhancedImage;
  } while (result.status === 'QUEUED');

  if (result.status === 'ERROR') throw new Error(`Enhancement error: ${result.errorCode}`);
  return result.fullUrl;
}
```


# Credits

VIESUS Cloud credit model — per-image pricing, PDF formulas, subscription DPI limits, and upload retention.

VIESUS Cloud uses a credit system. Credits are consumed per enhancement based on the features applied. Unused credits in a billing period do not carry forward unless specified by your subscription plan.

***

## Check remaining credits

```graphql
query {
  credits {
    periodStart
    periodEnd
    usedCreditsThisPeriod
    remainingCreditsThisPeriod
  }
}
```

***

## Image enhancement credits

When multiple features are active in a single enhancement, only the **highest-cost feature** is charged — credits do not add up.

| Feature             | Credits per image |
| ------------------- | ----------------- |
| Color Enhancement   | 1                 |
| Restoration         | 1                 |
| Background Handling | 4                 |
| AI Upscaling        | 4                 |

### Examples

| Features active                    | Charged                          |
| ---------------------------------- | -------------------------------- |
| Color Enhancement only             | 1 credit                         |
| Color Enhancement + Restoration    | 1 credit (both cost 1; max is 1) |
| Color Enhancement + AI Upscaling   | 4 credits (max of 1 and 4)       |
| Background Handling + AI Upscaling | 4 credits (max of 4 and 4)       |
| All features combined              | 4 credits                        |

***

## PDF enhancement credits

PDF credits are calculated from the analysis results. Run [PDF analysis](https://github.com/Viesus-AG/gitbook-sync/blob/main/viesus-docs/reference/cloud-api/pdf-enhancement/README.md#step-2--wait-for-analysis) first — the `metadata` field reports estimated cost before you commit to an enhancement.

The analysis reports three numbers:

* **Total** — total embedded images in the PDF
* **Enhancement** — images eligible for color enhancement
* **Resizing** — images eligible for AI upscaling

**Credit formulas:**

```powershell
Base cost     = Total ÷ 2 × 1
Resizing cost = Resizing × 3
Color cost    = Enhancement × 1

All features  = Base + Resizing + Color
No upscaling  = Base + Color
No color      = Base + Resizing
```

### Example calculation

PDF with 40 total images, 31 eligible for color, 9 eligible for resizing:

Scenario Calculation Credits
All features 40÷2 + 31×1 + 9×3 = 20 + 31 + 27 78
No upscaling 20 + 31 51
No color enhancement 20 + 27 47

***

## AI upscaling limits

| Constraint                | Value                       |
| ------------------------- | --------------------------- |
| Maximum input dimension   | 3,000 px (width or height)  |
| Maximum enlargement ratio | 4×                          |
| Maximum output dimension  | 11,996 px (width or height) |

**PDF output resolution limits by subscription:**

| Subscription | Maximum target resolution |
| ------------ | ------------------------- |
| Free         | 300 DPI                   |
| Basic        | 600 DPI                   |
| Business     | 1,200 DPI                 |

***

## Upload retention

Uploads are stored for **30 days** by default, then automatically deleted. You are not charged for storage — this is a data management setting.

**Change default retention for new uploads:**

```graphql
mutation {
  updateFileRetention(days: 7) {
    uploadRetentionDays
  }
}
```

This applies to uploads made after the change. Existing uploads keep their original 30-day retention.

**Delete an upload immediately:**

```graphql
mutation {
  deleteUploads(ids: ["upload-id"]) {
    deletedUploadIds
  }
}
```

Multiple uploads can be deleted in one call by passing multiple IDs.

***

## Managing costs

**Review PDF credit estimate before enhancing** — the analysis phase is free. Check `metadata.totalCredits` before calling `createEnhancedImage`.

**Disable upscaling when not needed** — set `targetResolution` to match the actual embedded image resolution to avoid triggering resizing credits.

**One upload, multiple enhancements** — the same upload can be enhanced multiple times without re-upload costs. Use this to test different parameter combinations cheaply.

**Track usage by period** — use the `credits` query to monitor consumption and avoid surprises at billing time.


# Webhooks

Receive real-time enhancement notifications via VIESUS Cloud webhooks. Setup, signature verification, retry behavior, and delivery logs.

Webhooks deliver push notifications to your server when an enhancement completes (or fails). This eliminates the need to poll the API and is the recommended pattern for production integrations.

Up to **5 webhooks** can be registered per account. Webhooks fire only for enhancements triggered via the API — not for enhancements run through the dashboard UI.

***

## Create a webhook

```graphql
mutation {
  createWebhook(input: {
    url: "https://your-server.com/webhooks/viesus"
  }) {
    id
    url
    secret
    createdAt
  }
}
```

Save the returned `secret` immediately — it is used to verify incoming requests and is **shown only once**. If lost, delete the webhook and create a new one.

***

## List webhooks

```graphql
query {
  webhooks {
    id
    url
    createdAt
  }
}
```

## Retrieve a single webhook

```graphql
query {
  webhook(id: "webhook-id") {
    id
    url
    secret
    createdAt
  }
}
```

***

## Delete a webhook

```graphql
mutation {
  deleteWebhook(id: "webhook-id") {
    success
  }
}
```

***

## Webhook payload

When an enhancement finishes, VIESUS Cloud sends a `POST` request to your URL with a JSON body:

```json
{
  "id": "eventId",
  "event": "upload.sub_status_update",
  "data": {
    "id": "uploadId",
    "status": "UPLOAD_FINISHED",
    "subStatus": "METADATA_ANALYZED_SUCCESSFULLY",
    "filesize": 297400,
    "mimetype": "application/pdf",
    "originalFilename": "photobook.pdf",
    "filename": "photobook.pdf",
    "startedAt": "2025-05-15T00:00:00.000Z",
    "finishedAt": "2025-05-15T00:00:12.000Z",
    "duration": 12000,
    "metadata": {
      "statistics": {},
      "totalCredits": 78
    }
  },
  "created": "2025-05-15T14:12:37.501Z"
}
```

Your endpoint must return a `2xx` status code to acknowledge delivery. Non-2xx responses trigger retries.

***

## Verifying webhook signatures

Every incoming webhook request includes an `x-viesus-cloud-signature` header containing an **HMAC-SHA256** hash of the raw request body, signed with your webhook `secret`.

Always verify this signature before processing the payload to ensure the request came from VIESUS Cloud.

**Node.js (Express):**

```js
const crypto = require('crypto');
const express = require('express');

const app = express();

// Use raw body buffer for signature verification
app.use('/webhooks/viesus', express.raw({ type: 'application/json' }));

app.post('/webhooks/viesus', (req, res) => {
  const signature = req.headers['x-viesus-cloud-signature'];
  const secret = process.env.VIESUS_WEBHOOK_SECRET;

  const expected = crypto
    .createHmac('sha256', secret)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);
  console.log('Received event:', event.event, event.data.id);

  // Process the event...

  res.sendStatus(200);
});
```

{% hint style="danger" %}
Compute the HMAC over the **raw request body bytes**, not a re-serialized JSON object. Any whitespace or key ordering difference produces a different hash and breaks verification.
{% endhint %}

**Python (Flask):**

```python
import hmac
import hashlib
import os
from flask import Flask, request, abort

app = Flask(__name__)

@app.route('/webhooks/viesus', methods=['POST'])
def webhook():
    secret = os.environ['VIESUS_WEBHOOK_SECRET'].encode()
    signature = request.headers.get('x-viesus-cloud-signature', '')
    expected = hmac.new(secret, request.get_data(), hashlib.sha256).hexdigest()

    if not hmac.compare_digest(expected, signature):
        abort(401)

    event = request.get_json()
    print(f"Received: {event['event']} for {event['data']['id']}")
    return '', 200
```

A full Node.js example is available at: 

***

## Retry behavior

If your endpoint does not return a `2xx` response within the timeout, VIESUS Cloud retries delivery **9 times** with a **1-hour delay** between attempts. After 9 failures the event is marked as permanently failed.

Design your endpoint to be idempotent — it may receive the same event multiple times.

***

## Webhook logs

Inspect delivery history for debugging failed webhooks:

```graphql
query {
  webhookLogs(
    webhookId: "webhook-id"
    filter: {
      take: 25
      skip: 0
    }
  ) {
    items {
      id
      webhookData
      responseBody
      responseStatusCode
      status
      createdAt
    }
  }
}
```

Filter by outcome:

```graphql
filter: { take: 25, skip: 0, status: FAILED }
```

***

## Events reference

The Cloud API documents a single webhook event:

| Event                      | When it fires                                                                                                                                               | Key fields                                                     |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `upload.sub_status_update` | An upload's status / sub-status changes — e.g. PDF analysis progress (`METADATA_ANALYZING` → `METADATA_ANALYZED_SUCCESSFULLY` / `METADATA_ANALYZED_FAILED`) | `data.status`, `data.subStatus` — branch your handler on these |

To check whether an **enhancement** has finished, query `enhancedImage { status fullUrl errorCode }` — `status` is `QUEUED`, `FINISHED`, or `ERROR`. The API does not document a separate webhook event name for enhancement completion.


# C/C++ SDK

Integrate the VIESUS enhancement engine directly into C/C++ applications via the IsEnhance.h native API. When to use the SDK, platform support, and how to get access.

The VIESUS CLI, PDF Enhancer, and Node.js module are all built on the same C++ enhancement library. The SDK gives you direct access to that library — enhancement becomes a function call inside your application rather than an external subprocess.

{% hint style="info" %}
The SDK is the highest-effort integration option. **Most teams should start with the** [**CLI**](/reference/cli-reference)**, the** [**Node.js Module**](/reference/node.js-module/overview)**, or the** [**Cloud API**](/reference/cloud-api/overview)**.** Use the SDK only when those don't meet your needs.
{% endhint %}

***

## When to use the SDK

Use case Why the SDK
Tight latency budget No subprocess startup cost per image. The library stays loaded in your process.
High-frequency calls Worth avoiding the CLI's per-call overhead when you process tens of thousands of small operations.
Existing C/C++ stack Native linking is cleaner than shelling out to the CLI from C/C++.
Custom pipeline integration Embed enhancement inside an existing image-processing pipeline rather than around it.
Non-C language with FFI Any language with a C foreign-function interface (Python, Go, Rust, Java JNI, .NET P/Invoke) can call the SDK directly.

## When **not** to use the SDK

* **One-shot batch processing** — use the [CLI](/reference/cli-reference). Simpler, no compilation.
* **Hot folder ingest** — use the [Folder Enhancer or PDF Enhancer](/reference/pdf-cli). Already built for this.
* **Node.js / TypeScript stack** — use the [Node.js module](/reference/node.js-module/overview). Native bindings already provided.
* **Cloud or low-effort deploy** — use the [Cloud API](/reference/cloud-api/overview). No infrastructure to manage.

***

## Platform support

Platform SDK availability
Windows (x64) Supported
Linux (x64) Supported
Linux (ARM64) Supported
macOS Library available — contact support
iOS Library available since V8.50 — contact support
Android Not currently supported

GPU acceleration (for AI features) requires CUDA 12.6 and an NVIDIA GPU with Ampere architecture or newer.

***

## Architectural benefits

The SDK is the **same C++ engine** that powers every other VIESUS interface:

* Same enhancement algorithms
* Same `viesusini.json` configuration format
* Identical output for the same input and configuration
* Same licensing model (GUID or Software Key)

This means you can prototype with the CLI, then migrate to the SDK without changing your configuration or expecting different results.

***

## API surface

The primary header is `IsEnhance.h`. The API exposes:

* Engine initialisation and configuration loading
* Per-image enhancement calls (synchronous)
* Per-image enhancement with progress callbacks (asynchronous)
* GPU model loading/unloading hooks (relevant for `VIESUS_UNLOAD` workflows)
* License management entrypoints

Detailed function signatures, threading model, memory ownership, and example code ship with the SDK package.

***

## How to get the SDK

The SDK is not a self-service download. Access is granted as part of an SDK-tier license agreement with Viesus AG, which includes:

* Headers, libraries, and sample code
* The bundled AI model files (large; not in the public installer)
* A dedicated technical contact during integration
* Build configurations for your target platforms

{% hint style="info" %}
**To request SDK access**, email  with:

* Your company and intended product
* Target platforms (OS, architecture, GPU presence)
* Expected production volume
* Whether you need GPU AI features (AI upscaling, Facial Reconstruction, Artifacts Removal)
  {% endhint %}


# Performance Tuning

Tune VIESUS throughput for CPU and GPU deployments — thread counts, configuration impact, image sizing, and benchmarking methodology.

This guide covers the key levers for maximizing VIESUS throughput across all on-premise interfaces (CLI, PDF Enhancer, Node.js module).



***

## The three variables that matter most

1. **Worker / instances count** — how many images process simultaneously
2. **Configuration (viesusini.json)** — which features are active; AI features are significantly slower
3. **Image size** — larger images take proportionally longer

Everything else (disk speed, CPU model, RAM bandwidth) is secondary on modern hardware.

***

## CPU: Instances count

### CLI

The CLI is single-threaded per invocation — it processes one image at a time. To parallelize, run multiple CLI instances in parallel with separate image lists:

```bash
# Split image list into 16 parts, run all in parallel
split -n l/16 images.lst /tmp/batch_
for f in /tmp/batch_*; do
    viesus -g "$GUID" -l "$f" -s -p config.json &
done
wait
```

### Node.js module

Set `UV_THREADPOOL_SIZE` to match physical CPU cores. Hyperthreading provides marginal benefit for VIESUS's compute workload:

```bash
export UV_THREADPOOL_SIZE=$(nproc --physical)
node server.js
```

***

## GPU: one worker per GPU

GPU processing requires one process/worker per GPU. Multiple processes sharing a GPU cause VRAM contention:

**CLI:**

```bash
CUDA_VISIBLE_DEVICES=0 viesus -g "$GUID" -l batch1.lst -s -p config.json &
CUDA_VISIBLE_DEVICES=1 viesus -g "$GUID" -l batch2.lst -s -p config.json &
wait
```

**Node.js:**

```js
const nGPUs = 2;
const pool = new StaticPool({
  size: nGPUs,
  task: './worker.js',
  workerData: process.env.VIESUS_GUID,
});
```

***

## Configuration impact on throughput

Features in `viesusini.json` have very different costs:

| Feature                                | CPU cost  | GPU required | Notes                               |
| -------------------------------------- | --------- | ------------ | ----------------------------------- |
| Base enhancement                       | Low       | No           | Always active                       |
| Noise reduction                        | Low       | No           |                                     |
| Face detection                         | Low       | No           | Adds overhead only when faces found |
| JPEG artifact removal (`ARmode: 0`)    | Low       | No           | Classical detection                 |
| JPEG artifact removal (`ARmode: 1`)    | High      | Yes          | AI detection and removal            |
| Background handling (`BGmode: 1`)      | High      | Yes          | AI segmentation                     |
| Classical resize (`ResizeMode` 0–4, 6) | Medium    | No           | CPU interpolation, no AI upscaling  |
| AI Upscaling (`ResizeMode` 5, 7–12)    | Very high | Yes          | 5–50× slower than classical         |

**Profile before optimizing:** run a sample batch with `WriteResultFiles: 1` and measure actual per-image times. Don't disable features without knowing their actual cost.

***

## Quality vs. speed

The `ResizeMode` you choose trades quality against throughput:

| Scenario                           | Recommended `ResizeMode` | Notes                                              |
| ---------------------------------- | ------------------------ | -------------------------------------------------- |
| Highest quality, time not critical | `5` (SR ×4 quality)      | Best results                                       |
| Production batch — balanced        | `7` (SR ×2 / ×4 auto)    | Auto-selects 2× or 4× based on resize factor       |
| Maximum throughput                 | `9` (SR ×4 fast)         | \~2–3× faster than mode 5, small quality trade-off |
| CPU-only (no GPU)                  | `6` (classical, no SR)   | Avoids slow GPU-dependent models                   |

***

## Hardware recommendations

| Use case                     | Recommended hardware              | Why                                                                                |
| ---------------------------- | --------------------------------- | ---------------------------------------------------------------------------------- |
| AI Upscaling (production)    | Nvidia RTX A4000 / A5000 or newer | 16+ GB VRAM handles Extra Large images; current architecture for model support     |
| AI Upscaling (development)   | Nvidia RTX 3060 / 4060 or newer   | 12 GB VRAM is enough for Small–Large images; good iteration speed                  |
| Traditional enhancement only | CPU (8+ cores)                    | Run multiple parallel instances to use all cores; no GPU required                  |
| Mixed AI + traditional       | Single GPU + CPU                  | AI features use the GPU; the traditional pipeline runs on CPU — they don't contend |

***

## Memory sizing

Plan system RAM as: `workers × memory_per_worker + OS overhead`

| Configuration              | RAM per worker        |
| -------------------------- | --------------------- |
| CPU, base enhancement only | 200–500 MB            |
| CPU, with AI features      | 1–2 GB                |
| GPU worker                 | 500 MB RAM + GPU VRAM |

NVIDIA GPU VRAM requirements:

* AI upscaling: \~4–6 GB per instance
* Background Handling: \~2–4 GB per instance
* Combined AI features: \~6–8 GB per instance; requires ≥8 GB VRAM card

***

## Benchmarking methodology

Always benchmark with:

1. **Representative images** — same resolution, format, and quality mix as production
2. **Warm runs** — discard the first run (cold caches, lazy GPU init)
3. **Steady-state measurement** — measure throughput over 500+ images, not a handful
4. **All features enabled** — benchmark the configuration you'll run in production

Measure both images/second and seconds/image. The former measures throughput; the latter measures user-facing latency.

```bash
# Simple throughput benchmark
START=$(date +%s%N)
viesus -g "$GUID" -l 1000_images.lst -s -p config.json
END=$(date +%s%N)
ELAPSED=$(( (END - START) / 1000000 ))  # ms
echo "1000 images in ${ELAPSED}ms = $(echo "scale=2; 1000000/$ELAPSED" | bc) img/sec"
```

***

## Reference benchmarks

Measured throughput figures live on the [Benchmarks](/operations/benchmarks) page.


# Benchmarks

Reference throughput benchmarks for VIESUS across presets, the factors that affect performance, and how to size a deployment.

VIESUS is designed to scale across hardware tiers and production volumes. The figures below are baselines under controlled conditions — your real-world results vary with hardware, image content, and the quality vs. speed settings you choose.

{% hint style="info" %}
These benchmarks are baselines, not guarantees. Always run a representative sample of your own production images on your target hardware before sizing infrastructure.
{% endhint %}

***

## Throughput by preset

All configurations are benchmarked on the **same reference system**. The **Standard** test set represents average customer images — a realistic spread of sizes and content. With this content, roughly **10% of images trigger 2× AI upscaling, 20% trigger 4×, and 20% trigger Artifact Removal**, and **vScene runs on every image**. **Background Removal** is measured on a **separate** set where 100% of images have their background removed.

Each configuration maps to a ready-made preset — see the [Presets Gallery](/configuration/presets-gallery).

{% hint style="warning" %}
The figures below are placeholders (**TBD**) pending a full test run.
{% endhint %}

| Configuration              | Image set      | Avg time / image | Throughput (images / hour) |
| -------------------------- | -------------- | ---------------: | -------------------------: |
| Default (base enhancement) | Standard       |              TBD |                        TBD |
| vScene on                  | Standard       |              TBD |                        TBD |
| 2× AI upscaling            | Standard       |              TBD |                        TBD |
| 4× AI upscaling            | Standard       |              TBD |                        TBD |
| Artifact Removal           | Standard       |              TBD |                        TBD |
| Background Removal         | Background set |              TBD |                        TBD |

Reference system: **TBD**.

***

## What affects performance

| Category          | Factors                                                                                                                                                                                      |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Image**         | Source resolution (cost grows with pixel count), content complexity (many faces, dense textures), compression level (heavily compressed JPEGs may trigger AI Artifact Removal as a pre-step) |
| **Configuration** | Upscaling factor, quality mode (Fast / Standard / High Quality), AI upscaling intensity, Facial Reconstruction settings                                                                      |
| **Hardware**      | GPU model and VRAM (insufficient VRAM causes paging and slowdowns), CPU, storage (SSD I/O for high-batch throughput)                                                                         |
| **Workflow**      | Number of parallel instances (scales until the GPU saturates), batch size (amortises model load), surrounding pipeline steps (download, archive, upload)                                     |

For how to tune these levers, see [Performance Tuning](/operations/performance-tuning).

***

## Sizing your deployment

A practical sizing approach:

{% stepper %}
{% step %}
**Pick a representative sample** of your actual production images (1,000–5,000 is plenty).
{% endstep %}

{% step %}
**Run them on the candidate hardware** with your target configuration (`viesusini.json`).
{% endstep %}

{% step %}
**Measure end-to-end time** including I/O, not just enhancement time.
{% endstep %}

{% step %}
**Multiply by your daily volume** to estimate capacity and add 30–50% headroom.
{% endstep %}
{% endstepper %}

For hardware recommendations and the full set of tuning levers, see [Performance Tuning](/operations/performance-tuning).


# Monitoring

Monitor VIESUS deployments — result files, error codes, log parsing, GPU metrics, and alerting patterns for on-premise and cloud.

Production observability for VIESUS. This page covers the signals each deployment exposes — per-image result files, structured logs, GPU metrics, and Cloud API events — and the thresholds worth alerting on.

***

## On-premise monitoring

### Result files

When `WriteResultFiles: 1` is set in `viesusini.json`, VIESUS writes a `.json` or `.res` file alongside each output image. These files contain per-image processing details and are the primary observability signal for on-premise deployments.

**Node.js / CLI result JSON:**

```json
{
  "brightCorrStrength": 0.011,
  "colorCorrStrength": 0.083,
  "fdApplied": 1,
  "ieApplied": 1,
  "isArtificial": 0,
  "isMonochrome": 0,
  "rszApplied": 0,
  "arApplied": 1
}
```

All fields are `0` or a float strength value. A result file present means the image processed. A missing result file (when `WriteResultFiles: 1`) means the enhancement failed.

**PDF Enhancer XML report:**

```xml

  
  
  
  ...

```

Error code `0` = success. Non-zero = partial or complete failure. See [PDF Error Codes](/support/error-codes/pdf).

***

### Parsing result files

**Check for CLI/Node.js errors (bash):**

```bash
#!/bin/bash
# Scan output folder for failed enhancements (missing result files)

IN_DIR="$1"
OUT_DIR="$2"
RES_DIR="$3"
ERRORS=0

while IFS= read -r img; do
    base=$(basename "${img%.*}")
    if [[ ! -f "${RES_DIR}/${base}.json" ]]; then
        echo "MISSING result: $img"
        ((ERRORS++)) || true
    fi
done < <(find "$IN_DIR" -type f -name "*.jpg")

echo "Errors: $ERRORS"
```

**Parse PDF XML reports:**

```bash
for xml in /print-queue/ready/*.xml; do
    code=$(xmllint --xpath 'string(//error/@code)' "$xml" 2>/dev/null)
    pdf=$(basename "${xml%.xml}")
    if [[ "$code" != "0" ]]; then
        echo "PDF ERROR: $pdf code=$code"
    fi
done
```

***

### Node.js module logging

Log both enhancement time and wall-clock time per job to detect pool saturation:

```js
parentPort.on('message', (job) => {
  const start = Date.now();
  const result = viesusObj.Enhance(job.fromPath, job.toPath, job.iniPath, job.resPath);
  const wall = Date.now() - start;
  parentPort.postMessage({ result, wall });
});
```

In the main thread:

```js
const { result, wall } = await pool.exec(job);
console.log(JSON.stringify({
  ts: new Date().toISOString(),
  status: result > 0 ? 'ok' : 'error',
  enhanceMs: result > 0 ? result : null,
  errorCode: result < 0 ? result : null,
  wallMs: wall,
  file: path.basename(job.fromPath),
}));
```

Structured JSON logs integrate cleanly with log aggregators (Datadog, Loki, CloudWatch).

**Key metrics to track:**

| Metric               | Alert threshold                                     |
| -------------------- | --------------------------------------------------- |
| `enhanceMs` p95      | 2× baseline — indicates degraded performance        |
| `wallMs - enhanceMs` | > 5 sec — pool is saturated (jobs queuing)          |
| Error rate           | > 1% — investigate error codes                      |
| Queue depth          | Monitor `pool.queueSize` if exposed by pool library |

***

### GPU monitoring

Check GPU utilization and VRAM usage alongside VIESUS metrics:

```bash
# One-line GPU status
nvidia-smi --query-gpu=name,utilization.gpu,memory.used,memory.total,temperature.gpu \
           --format=csv,noheader,nounits

# Continuous monitoring (every 2 seconds)
nvidia-smi dmon -s u,m -d 2

# NVML-based detailed stats (Python)
# pip install nvidia-ml-py
```

**Expected values during active GPU processing:**

| Metric          | Expected range                    |
| --------------- | --------------------------------- |
| GPU utilization | 80–100%                           |
| VRAM used       | 4–8 GB per active worker          |
| Temperature     | < 85°C (thermal throttling above) |

***

### License expiry monitoring

When a license expires, VIESUS stops enhancing — images pass through unchanged (output = input). Check license validity directly with the CLI's `-I` flag rather than inferring it from output:

```bash
#!/bin/bash
# check-license.sh — verify the VIESUS license is valid; run daily via cron

GUID="$1"

# -I prints license information (validity and, where applicable, expiry).
# For GUID libraries the GUID must be supplied with -g.
if ! info=$(viesus -I -g "$GUID"); then
    echo "ALERT: 'viesus -I' failed (exit $?) — license may be invalid or expired"
    exit 1
fi

echo "$info"
# Review the validity / expiry fields and alert when the license is invalid
# or close to expiry.
```

Run this check daily via cron and alert on a non-zero exit code.

***

## Cloud API monitoring

### Credit balance

Poll credit balance to detect approaching depletion:

```js
async function checkCredits(client) {
  const { credits } = await client.request(gql`
    query {
      credits {
        remainingCreditsThisPeriod
        usedCreditsThisPeriod
        periodEnd
      }
    }
  `);

  const remaining = credits.remainingCreditsThisPeriod;
  const periodEnd = new Date(credits.periodEnd);
  const daysLeft = Math.ceil((periodEnd - Date.now()) / 86400000);

  console.log(`Credits: ${remaining} remaining, ${daysLeft} days until period end`);

  if (remaining < 500) {
    // Alert: less than 500 credits remaining
    await sendAlert(`Low credits: ${remaining} remaining until ${credits.periodEnd}`);
  }
}
```

### Enhancement failure rate

Track error rates from webhook events:

```js
// In your webhook handler
const metrics = { finished: 0, errored: 0 };

if (status === 'FINISHED') metrics.finished++;
if (status === 'ERROR') {
  metrics.errored++;
  console.error(JSON.stringify({ event: 'enhancement_error', errorCode, uploadId }));
}

// Log hourly
setInterval(() => {
  const errorRate = metrics.errored / (metrics.finished + metrics.errored) * 100;
  console.log(`Enhancement error rate: ${errorRate.toFixed(2)}%`);
  metrics.finished = 0;
  metrics.errored = 0;
}, 3600000);
```

### Webhook delivery failures

Query webhook logs regularly to catch failed deliveries:

```graphql
query {
  webhookLogs(
    webhookId: "your-webhook-id"
    filter: { take: 50, skip: 0, status: FAILED }
  ) {
    items {
      id
      responseStatusCode
      createdAt
    }
  }
}
```

***

## Alerting recommendations

| Alert                     | Condition                                     | Priority |
| ------------------------- | --------------------------------------------- | -------- |
| Enhancement error rate    | > 2% over 15 min                              | High     |
| Pool saturation           | `wallMs - enhanceMs` > 10 sec p95             | High     |
| License invalid / expired | `viesus -I` exits non-zero or reports invalid | Critical |
| Low credits               | < 500 remaining                               | High     |
| GPU temperature           | > 85°C                                        | High     |
| Webhook failures          | > 5 consecutive failed deliveries             | Medium   |


# Security

Security guidance for VIESUS deployments — GUID management, API key storage, network isolation, Docker security, and input validation.

Security guidance for production VIESUS deployments — protecting your license credentials, hardening any API you expose, isolating the service on the network, and locking down containers.

***

## GUID and API key management

The GUID (on-premise) and API key (VIESUS Cloud) are credentials that allow VIESUS processing under your license. Treat them like passwords.

### What to avoid

| Action                                               | Why it's a risk                                           |
| ---------------------------------------------------- | --------------------------------------------------------- |
| Hardcode GUID in source code                         | GUID visible to anyone with code access or in git history |
| Commit GUID to version control                       | Credentials in git history are hard to revoke completely  |
| Log the GUID                                         | Credentials in log aggregators and monitoring tools       |
| Pass GUID as a command-line argument visible in `ps` | Visible to all users on the system                        |
| Bake GUID into a Docker image                        | Image layers store the value, visible in registries       |

### Recommended patterns

**Environment variables:**

```bash
export VIESUS_GUID="$(cat /run/secrets/viesus_guid)"
node server.js
```

**Secrets manager (AWS Secrets Manager example):**

```js
const { SecretsManagerClient, GetSecretValueCommand } = require('@aws-sdk/client-secrets-manager');

async function getGuid() {
  const client = new SecretsManagerClient({ region: 'eu-west-1' });
  const response = await client.send(
    new GetSecretValueCommand({ SecretId: 'viesus/guid' })
  );
  return response.SecretString;
}

const GUID = await getGuid();
```

**Docker secrets (Swarm):**

```bash
echo "your-guid" | docker secret create viesus_guid -
```

```js
// Read from Docker secret file
const GUID = process.env.VIESUS_GUID ||
  fs.readFileSync('/run/secrets/viesus_guid', 'utf8').trim();
```

***

## GUID rotation

GUID-based licenses use the same GUID throughout the license term. When the license renews, the GUID stays the same but the library package is updated.

**If a GUID is compromised:**

1. Contact  immediately to request a GUID replacement.
2. Update the GUID in all running services.
3. Audit access to determine how the GUID was exposed.

***

## API surface hardening (Node.js service)

If you expose an HTTP API wrapping the VIESUS Node.js module:

**Validate and restrict file inputs:**

```js
const ALLOWED_MIME_TYPES = new Set(['image/jpeg', 'image/png', 'image/tiff', 'image/webp']);
const MAX_FILE_SIZE = 50 * 1024 * 1024; // 50 MB

app.post('/enhance', upload.single('image'), (req, res, next) => {
  if (!req.file) return res.status(400).json({ error: 'No file provided' });
  if (!ALLOWED_MIME_TYPES.has(req.file.mimetype)) {
    fs.unlink(req.file.path, () => {});
    return res.status(415).json({ error: 'Unsupported file type' });
  }
  if (req.file.size > MAX_FILE_SIZE) {
    fs.unlink(req.file.path, () => {});
    return res.status(413).json({ error: 'File too large' });
  }
  next();
});
```

**Restrict file paths to known directories:**

```js
const OUTPUT_DIR = path.resolve('./outputs');

function safeOutputPath(jobId, ext) {
  const filename = `${jobId}${ext}`;
  const full = path.join(OUTPUT_DIR, filename);
  // Prevent path traversal
  if (!full.startsWith(OUTPUT_DIR + path.sep)) {
    throw new Error('Invalid path');
  }
  return full;
}
```

**Rate limiting:**

```js
const rateLimit = require('express-rate-limit');

app.use('/enhance', rateLimit({
  windowMs: 60 * 1000, // 1 minute
  max: 20,             // 20 uploads per IP per minute
  message: { error: 'Too many requests' },
}));
```

***

## Network isolation

On-premise VIESUS deployments make **no outbound network connections** for licensing. GUID licenses are passed at runtime, and Activation Keys (also called Software Keys) are activated **offline** via a request/activation-file exchange — neither contacts a license server at runtime, so the service can run fully air-gapped.

**Firewall recommendations:**

| Direction                    | Rule                                                        |
| ---------------------------- | ----------------------------------------------------------- |
| Inbound to VIESUS service    | Allow only from your application servers or load balancer   |
| Outbound from VIESUS service | Deny all — on-premise licensing requires no internet access |

**Docker network isolation:**

```yaml
# docker-compose.yml
services:
  viesus-enhance:
    networks:
      - internal

  nginx:
    networks:
      - internal
      - external

networks:
  internal:
    internal: true   # No internet access
  external:
```

***

## Docker security

**Run as a non-root user:**

```dockerfile
RUN useradd -r -s /bin/false viesus
USER viesus
```

**Read-only filesystem:**

```bash
docker run \
  --read-only \
  --tmpfs /tmp \
  --tmpfs /app/uploads \
  --tmpfs /app/outputs \
  viesus-enhance:latest
```

**Drop capabilities:**

```yaml
cap_drop:
  - ALL
cap_add:
  - NET_BIND_SERVICE  # only if binding port < 1024
security_opt:
  - no-new-privileges:true
```

***

## Webhook endpoint security

When receiving VIESUS Cloud webhooks, always verify the HMAC signature before processing:

```js
function verifyWebhook(rawBody, signatureHeader, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(rawBody)
    .digest('hex');

  // Use timingSafeEqual to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(expected, 'hex'),
    Buffer.from(signatureHeader, 'hex')
  );
}
```

Never skip signature verification even for development — the webhook endpoint may receive untrusted external traffic.

***

## Input file security

VIESUS processes image files. Malformed or malicious images (designed to exploit image parsing) are a theoretical concern for any image processing pipeline. Mitigations:

* Run VIESUS in an isolated environment (container or VM) with no access to sensitive data
* Do not process user-uploaded files as the same OS user that has access to credentials or other sensitive system resources
* Scan inputs with a virus scanner for enterprise deployments accepting external files


# 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](/support/troubleshooting). For specific error codes, see [Error Codes](/support/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](https://www.viesus.cloud/) and start enhancing.





What's the fastest way to try VIESUS?

The [Cloud Quickstart](/get-started/quickstart-cloud) takes a few minutes — no install, no license. For on-premise, follow the [Image Enhancement Quickstart](/get-started/quickstart-image-enhancement) (or [PDF Enhancement Quickstart](/get-started/quickstart-pdf-enhancer) 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](/discover/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  for a quote tailored to your volume and workflow.





How do I create a license request file?

In the [VIESUS Viewer](/tools/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](/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](/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](/features/features/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.

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





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.

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





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](/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](/installation/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](/operations/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?

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.





Where do I see the latest VIESUS features?

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



***

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

Use the [VIESUS Viewer](/tools/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](/reference/docker/cli) and [Node.js → Docker](/reference/docker/nodejs).





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



***

## Troubleshooting



My GUID doesn't work — what should I check?

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"`.





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





Where else can I find help?

* [Troubleshooting](/support/troubleshooting) — cross-product guide
* [Error Codes](/support/error-codes) — specific exit codes
*  — 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?

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





How do I check whether PDF processing was successful?

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

```xml

```

Error code `0` = success. Any non-zero code indicates a failure. See [PDF Error Codes](/support/error-codes/pdf) 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:

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





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:

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.





How do I skip cover pages from PDF processing?

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




# Troubleshooting

Symptom-based fixes for VIESUS — first-run and install blockers, plus CLI, PDF Enhancer, Node.js module, and VIESUS Cloud issues.

Symptom-based fixes spanning the first run and every interface. For specific exit/error codes, see [Error Codes](/support/error-codes).



***

## Quick fixes

| Symptom                | First thing to try                                                                 |
| ---------------------- | ---------------------------------------------------------------------------------- |
| `viesus` not found     | Add the VIESUS install dir to `PATH`, or restart your terminal                     |
| GUID not accepted      | Confirm the library version matches the install (`viesus -v`)                      |
| License rejected       | Re-run the license activation and restart the system                               |
| CLI hangs              | Check disk space at the output path; restart if needed                             |
| Slow processing        | Check disk I/O, use local storage, run multiple instances rather than more threads |
| No output produced     | Pass an output flag (`-s`, `-b`, or `-n`) — the CLI writes nothing without one     |
| Output looks unchanged | Set `SKIPmode: 0` and `Enhancemode: 1`; test with a clearly low-quality image      |

***

## First run

The issues that most commonly block a first install and first run.

### Installation failed or gave a warning

**Windows — "Windows protected your PC":** Click **More info** → **Run anyway**. The installer is signed by Viesus AG; SmartScreen blocks it because it's not a widely-distributed consumer application.

**Windows — installer fails silently:** Right-click the `.exe` → **Run as administrator**. The installer requires elevated privileges.

**Linux — dependency error during `dpkg -i`:**

```bash
sudo apt-get install -f
```

This resolves any missing shared library dependencies left over from the `.deb` install.

### `viesus: command not found`

The VIESUS executable installs at `/usr/local/viesus/viesus`, which is not on `PATH` by default.

**Run directly:**

```bash
/usr/local/viesus/viesus -v
```

**Add to PATH permanently (Linux):**

```bash
echo 'export PATH="/usr/local/viesus:$PATH"' >> ~/.bashrc
source ~/.bashrc
```

**Windows:** run from the VIESUS Viewer installation directory, or add it to the system PATH via System Properties → Environment Variables.

### GUID error on first run

```
Error: GUID wrong
```

1. Check for extra spaces — copy the GUID directly from your delivery email; do not type it.
2. Verify the GUID matches the library package you installed (the same GUID must come from the same delivery).
3. Wrap the GUID in quotes to avoid shell interpretation issues: `-g "your-guid-here"`.

### No output files produced

If `viesus` completes silently but no output images appear, check which output mode you specified:

| You want                                     | Add this flag           |
| -------------------------------------------- | ----------------------- |
| Output alongside input with `_viesus` suffix | `-s`                    |
| Output in a specific folder                  | `-b /path/to/output -s` |
| Custom suffix                                | `-n "_mysuffix"`        |

The CLI does not produce output without one of these flags — this is intentional.

### Images processed but look unchanged

* **`SKIPmode` is active:** `SKIPmode: 1` skips images VIESUS considers already enhanced — set `"SKIPmode": 0`.
* **`Enhancemode` is off:** set `"Enhancemode": 1`.
* **License expired:** VIESUS passes images through without enhancement. Check result files — `"ieApplied": 0` confirms enhancement did not run. Contact  to renew.
* **Input is already high quality:** VIESUS applies proportional corrections — minor input issues mean minor output change. Test with a clearly underexposed or noisy image.

***

## CLI and image enhancement

Runtime issues with the CLI and Viewer. For first-run/setup problems, see [First run](#first-run) above; for the full exit-code catalogue, see [CLI Exit Codes](/support/error-codes/cli).

### Very slow processing; GPU features not running

1. Check the NVIDIA driver: `nvidia-smi` must show CUDA version ≥ 12.6.
2. Verify AI features are enabled in `viesusini.json` (`ARmode: 1`, `ResizeMode: 10`, etc.) — they default to off.
3. Confirm the GPU add-on packages are installed (`viesus-sr`, `viesus-ar`, `viesus-bg`).
4. In Docker: verify `--gpus all` is passed and the NVIDIA Container Toolkit is installed.
5. Ensure no other instance (such as the Viewer) is running and holding the GPU.

Single-threaded processing is fastest per image (cache locality); parallelism comes from running multiple CLI instances, not from raising the thread count inside one. See [Benchmarks](/operations/benchmarks).

### Out of memory (OOM) errors

Reduce the number of parallel processes or workers. Each VIESUS worker with AI features needs 4–8 GB RAM plus GPU VRAM.

* **CLI:** reduce parallel invocations.
* **Node.js:** reduce `UV_THREADPOOL_SIZE`.
* **PDF Enhancer:** reduce `threads` in `settings.json` and `maxTargetSize`.

### Permission denied

Ensure write access to the output directory and exclusive read access to the input file (check that no other process has it open).

### Invalid configuration / JSON

* Validate JSON syntax — many editors silently leave trailing commas: `python -m json.tool < viesusini.json`.
* Check values are within range — see the [Parameter Reference](/configuration/parameter-reference).
* For unexpected results, start from a known-good [preset](/configuration/presets-gallery) and change one parameter at a time.

### Output images have an unexpected format

VIESUS writes output only when an output flag (`-s`, `-b`, or `-n`) is passed, and the path must use a supported extension. Supported output formats are `.jpg`, `.png`, and `.tif` — ensure your configured output path uses one of them.

### Licensing errors

License-related exit codes (`-90` to `-95` GUID errors, `-50` feature not licensed, `-70` daily limit) are catalogued in [CLI Exit Codes](/support/error-codes/cli).

***

## PDF Enhancer

### PDF processed but no images enhanced

1. Run with `justAnalyze: 1` in settings or the `-t` flag to check what images VIESUS detects.
2. Check `minImageWidth`, `minImageHeight`, `minFileSize` — images below these thresholds are skipped.
3. Check `skipFullPageBackground` — full-page background images are excluded when enabled.
4. Check `useColorRatio` — low-color-variation images (gradients, solid fills) may be filtered.

### XML report shows error code other than 0

See [PDF Error Codes](/support/error-codes/pdf) for the full table and solutions. Common errors:

* Code 7: input PDF not found — check the source path
* Code 12/14: output write failure — check destination folder permissions and disk space
* Code 20/26: VIESUS processing error — check the GUID and library installation

### Hotfolder not picking up new PDFs

1. Verify the `sourceFolder` path in `settings.json` is correct and accessible.
2. Check `triggerSuffix` — only files matching the suffix are picked up (default `.pdf`).
3. Check `pollInterval` — new files appear after the next poll.
4. Confirm the `viesusPDF` process is running: `ps aux | grep viesusPDF`

***

## Node.js module

### `Error: Cannot find module 'viesus'`

The native module is not installed. Install it:

```bash
sudo npm install /usr/local/viesus/node-viesus
```

Verify installation:

```bash
node -e "const v = require('viesus'); console.log('ok')"
```

### `Enhance()` returns a negative code

Look up the code in [Node.js API Reference: Error Codes](/reference/node.js-module/api-reference#error-codes). Common ones:

| Code          | Cause                             | Fix                                                    |
| ------------- | --------------------------------- | ------------------------------------------------------ |
| `-2` / `-378` | Wrong GUID                        | Check the GUID string                                  |
| `-4`          | Cannot load input image           | Verify the input file exists and is a supported format |
| `-5` / `-6`   | Cannot open file                  | Check file paths are absolute and accessible           |
| `-10` / `-11` | Parameter file not found or empty | Verify `iniPath` points to a valid `viesusini.json`    |
| `-13`         | Cannot write result file          | Check that the output directory exists and is writable |

### Workers initializing slowly

`MyViesusObject` initialization (first call per worker) loads the VIESUS engine and any enabled AI models. This is expected — 1–10 seconds per worker at startup depending on enabled features and hardware. Subsequent `Enhance()` calls are fast.

Do not create a new `MyViesusObject` per image. Create one per worker thread at startup and reuse it.

### Pool is saturated (high queue wait time)

The `wallMs` time in logs is much higher than `enhanceMs` — jobs are waiting in the queue for a free worker. Solutions:

* Increase `UV_THREADPOOL_SIZE` (up to available CPU cores)
* Add more hardware (CPU cores or GPUs)
* Reduce AI feature usage to speed up per-image time

***

## VIESUS Cloud

### API returns authentication error

1. Verify your API key is correct — copy it fresh from the dashboard.
2. Confirm the `x-api-key` header is spelled exactly right (lowercase).
3. Confirm the request goes to `https://api.viesus.cloud/graphql`.

### Enhancement status stuck at `QUEUED`

Normal for up to several minutes under load. If queued for > 10 minutes:

1. Check the API status page (if available).
2. Try creating a new enhancement — it may be a transient issue with that specific job.
3. Contact  with the enhancement ID.

### Webhook not receiving events

1. Verify your endpoint is publicly accessible — VIESUS Cloud cannot reach localhost.
2. Check your endpoint returns `2xx` — non-2xx responses are retried.
3. Query webhook logs for delivery history: see [Webhooks](/reference/cloud-api/webhooks#webhook-logs).
4. Confirm the webhook `url` in the `createWebhook` mutation was correct.

### PDF analysis fails repeatedly

Try re-triggering analysis:

```graphql
mutation {
  analyzePdf(uploadId: "your-upload-id") {
    success
  }
}
```

If it continues to fail, the PDF may be password-protected, corrupted, or contain no raster images. Contact  with the upload ID.

***

## Getting support

Contact  and include:

* VIESUS version: `viesus -v` (CLI) or the installed package version
* Platform: OS, architecture, CPU/GPU model
* Interface: CLI, PDF Enhancer, Node.js, Cloud
* Error codes or XML report content
* What you expected vs. what happened
* A sample image or PDF if the issue is content-specific (share privately if needed)

For Cloud API issues, include the `uploadId` or `enhancementId` from the API response.


# Error Codes

Complete catalogue of error codes returned by VIESUS interfaces — CLI exit codes, PDF Enhancer error codes, and Node.js module return codes.

Each VIESUS interface returns its own set of error codes. Pick the interface below, then look up the specific code on its reference page.

For symptom-based troubleshooting (when you don't have a specific code), see [Troubleshooting](/support/troubleshooting).

CLI Exit Codes Exit codes from the image-enhancement engine — general, processing, scene/AI, and license/GUID errors. CLI Exit Codes
PDF Enhancer Error Codes Error codes from the PDF Enhancer's XML processing report — system, file-system, PDF processing, trigger, and cropping errors. PDF Enhancer Error Codes
Node.js Error Codes Return codes from the Node.js module — positive values are processing times in ms, negative values indicate errors. Node.js Error Codes


# CLI Exit Codes

Complete reference of VIESUS CLI exit codes — meanings, categories, and what to do for each.

The VIESUS CLI is a wrapper around the IsEnhance library. It returns the library's return code offset by **−100** — e.g., CLI exit code `-104` corresponds to library error `-4` (missing parameter file). Exit code `0` means success. The tables below list the **library return codes**; subtract 100 from a code to get the CLI exit code.

For PDF Enhancer error codes, see [PDF Error Codes](/support/error-codes/pdf). For symptom-based troubleshooting, see [Troubleshooting → CLI](/support/troubleshooting#cli-and-image-enhancement).



***



Common license-related fixes

* **Feature not licensed** (codes `-50` to `-62`) — confirm the AI features you're using are included in your license with .
* **GUID error** (codes `-90` to `-95`) — verify the GUID is correct and the DLL version matches the install.





General errors (-1 to -20)

Code Description
-1 Enhancement object initialisation failed
-2 Incorrect memory organisation
-3 Enhancement validation failed
-4 Required filename parameter missing
-5 Failed to load INI/JSON configuration file
-6 Failed to save INI/JSON configuration file
-7 Invalid image pointer
-8 Invalid image data pointer
-9 Invalid processing parameters pointer
-10 Generic null pointer error
-11 Missing image enhancement analysis
-12 Failed to load ICC color profile
-13 Failed to retrieve license information
-14 Image already enhanced (use -a to force)
-15 Color management system analysis failed
-16 Resize analysis failed
-17 Resize region of interest out of limits
-18 Pre-processing analysis failed
-19 Face detection analysis failed
-20 Noise reduction analysis failed





Processing errors (-21 to -49)

Code Description
-21 Noise reduction processing failed
-22 Red-eye reduction analysis failed
-23 Red-eye reduction processing failed
-24 Global balance processing failed
-25 Sharpening processing failed
-26 Resize processing failed (check SR model)
-27 Incorrect data type provided
-28 Red-eye region processing failed
-29 Incorrect color channel order
-30 ICC profile validation failed
-31 Memory allocation failed
-32 Color conversion to sRGB failed
-33 Color conversion from sRGB failed
-34 Operation not supported
-35 Temporary color transform failed
-36 GGA processing failed
-37 AI upscaling resize failed
-45 Face reconstruction analysis failed
-46 Face reconstruction processing failed
-47 Background analysis failed
-48 Background processing failed
-49 Face blur processing failed





Scene, crop & AI processing errors (-96 to -103)

Code Description
-96 Scene-detection analysis failed
-97 Cropping failed
-98 Text-detection analysis failed
-100 AI Artifact Removal processing failed
-101 vScene preset not found
-102 vScene number invalid
-103 vScene label buffer too small





License errors (-50 to -99)

Code Description
-50 Feature not licensed
-51 LAB feature not licensed
-52 Image limit feature not licensed
-53 Windows feature not licensed
-54 macOS feature not licensed
-55 Linux feature not licensed
-60 PDF feature not licensed
-61 TRON PDF feature not licensed
-62 V8 feature not licensed
-71 License build time error
-72 License error 1
-73 License error 2
-90 to -95 GUID license errors (wrong GUID used with the library)
-99 No license service available




# PDF Enhancer Error Codes

Complete reference for all VIESUS PDF Enhancer error codes — meanings, causes, and fixes.

Error codes appear in the XML processing report (``). Code `0` means success; all non-zero codes indicate a processing failure.

For underlying CLI exit codes from the enhancement engine, see [CLI Exit Codes](/support/error-codes/cli). For settings-related issues, see the PDF [Settings Reference](/configuration/pdf-settings).



***



Common fixes by category

**File system issues (12, 14–18)**

* Verify all file and folder paths exist
* Check read / write permissions
* Ensure sufficient disk space

**Permission errors (21–22)**

* Run with appropriate user privileges
* Check file / folder permissions
* Ensure exclusive access to files

**PDF processing (6, 13, 23–28)**

* Verify PDF file integrity
* Check for password protection
* Confirm PDF version compatibility

**License (7, 36)**

* Verify license validity and expiration
* Check processing limits
* Contact 





General system errors (1–8)

Code Description
1 An unknown or unspecified error occurred
2 The PDF file has already been enhanced (use force option to re-process)
3 Failed to load the configuration/settings file
4 Unable to open the PDF document (file may be corrupted or password-protected)
5 Failed to create required directories
6 The input file is not a valid PDF document
7 License validation failed or license is invalid
8 PDF library initialisation or operation failed





File system & path errors (9, 12, 14–18)

Code Description
9 File size is below the minimum threshold for processing
12 The specified input file could not be found
14 The specified path does not exist
15 VIESUS configuration file not found
16 Destination folder does not exist or is not accessible
17 Archive folder does not exist or is not accessible
18 Debug folder does not exist or is not accessible





File operations & permissions (10–11, 21–22, 29)

Code Description
10 Failed to save the processed file
11 Error replacing images in the PDF
21 Insufficient file permissions for the operation
22 Failed to modify file permissions
29 Unable to delete the specified file





Configuration & parameters (19–20)

Code Description
19 Invalid or incorrect command-line parameters provided
20 General VIESUS processing error





PDF processing errors (13, 23–28)

Code Description
13 PDF library failed to initialise
23 Error during PDF flattening
24 PDF color conversion failed
25 PDF flattening initialisation failed
26 Image enhancement process failed
27 Failed to read image location data from PDF
28 No corresponding PDF found for TOX file





Trigger & workflow management (30–35)

Code Description
30 Failed to rename the trigger file
31 Error copying folders
32 Failed to delete the trigger file
33 Unable to rename the specified folder
34 Failed to create the trigger file
35 Error during file archiving





License & resource limits (36)

Code Description
36 Processing limit has been reached for the current license





Cropping & region processing (37–39)

Code Description
37 Invalid cropping rectangle specified
38 Cropping rectangle extends beyond page boundaries
39 Error during cropping operation





Best practices

1. **Log error codes.** Capture and log the specific code per failed file — error categories rely on knowing which codes you're hitting.
2. **Validate prerequisites.** Verify file permissions, paths, and license status before processing.
3. **Validate input.** Ensure PDFs are valid and not password-protected before queueing them.
4. **Monitor resources.** Check available disk space and memory continuously in production.
5. **Archive originals.** Use the archive setting to preserve source files before any destructive operation.



***

For configuration parameters, see [PDF Settings Reference](/configuration/pdf-settings). For the CLI, see [PDF CLI Reference](/reference/pdf-cli). For broader troubleshooting, see [Troubleshooting](/support/troubleshooting).


# Node.js Error Codes

Return codes from the VIESUS Node.js module — what each code means and when it occurs.

The Node.js module returns an integer after each enhancement call:

* **`> 0`** — enhancement succeeded; the value is the processing time in milliseconds.
* **`< 0`** — enhancement failed; the value is one of the error codes below.

For symptom-based troubleshooting, see [Troubleshooting](/support/troubleshooting).

***

## Error codes

Code Description
-1 Init failed
-2 GUID wrong
-3 Internal error
-4 Loading image not possible
-5 Can't open file
-6 File not found
-7 File is empty
-8 Mem open internal error
-9 Enhancement failed — contact support@viesus.com for further investigation
-10 Parameter file not found
-11 Parameter file empty
-12 Output format not supported
-13 Error writing result file

### Additional errors

Code Description
-126 Enhancement failed — image was already enhanced
-378 Enhancement failed — wrong GUID entered

Codes below **`-18`** (other than the named codes above) indicate internal errors. Contact  if you receive one.


# Changelog

VIESUS version history: what's new, what requires action, and feature additions per release.

Important changes per VIESUS version. Use this to verify which features are available in your installed version, and to plan upgrades.

{% hint style="info" %}
**Upgrading?** The configuration file is forward-compatible — load your existing `viesusini.json` into the latest VIESUS Viewer and save it to add newly available parameters with default values. See [FAQ → Can I migrate my existing config?](/support/faq#can-i-migrate-my-existing-iniandsol-json-config-to-a-new-viesus-version) for details.
{% endhint %}

For the complete PDF Enhancer changelog, see [PDF Enhancer Installation](/installation/pdf).

***



VIESUS 13

V13 brings updates in scene detection, HDR processing, AI upscaling, facial reconstruction, execution flow, and platform support.

#### Requires action

* Enable CPU-based vScene to use scene detection in CPU workflows
* Set `hdrstrength` to use HDR-to-SDR tonemapping
* Turn on `VSceneMode=1` to use scene-based 4× AI upscaling
* Set `arstrength` to control when Artifact Removal is applied
* Set `VIESUS_UNLOAD` if you need GPU model unloading on low-memory systems

#### Image quality improvements

* **vScene for CPU-based execution** — fast scene detection added for CPU workflows. VIESUS detects scene type and applies pre-defined or self-defined parameter settings.
* **HDR** — HDR-to-SDR tonemapping with gainmap application for better SDR reproduction. Controlled by `hdrstrength`.
* **Scene-based 4× AI upscaling** — `VSceneMode=1` enables scene-based SR. Landscape scenes without people use the sharper 4xAR model.
* **Age group-based Facial Reconstruction** — reduces unlikely teeth in baby faces by factoring in age group detection.
* **Improved monochrome AI upscaling** — better toned monochrome SR results and RGB facial reconstruction in monochrome detection cases.

#### Performance improvements

* **Improved 2× AI upscaling** — better speed, performance, and consistency.
* **Mixed execution** — fast TensorRT for default SR models, CUDA precision for Face Reconstruction.
* **Improved Face Detection** — GPU-optimised, no longer blocks the GPU execution pipeline.
* **`arstrength` parameter** — defines the threshold at which Artifact Removal is applied. Skip AR for lightly compressed images that don't justify it.
* **`VIESUS_UNLOAD` environment variable** — unload AI models from the GPU after execution. Trades performance for low-memory GPU support.

#### Platform support

* **NVIDIA Blackwell GPUs** — supported
* **ARM-based Linux systems** — supported





VIESUS 12

V12 brings updates in image adjustments, AI upscaling, artifact removal, facial processing, scene and text detection, parameter handling, and GPU infrastructure.

#### Requires action

* Use `ResizeMode 10` for 2xFast or 4xFast
* Use `ResizeMode 11` for 4xAR
* Set an Artifact Removal mode if you want the new AR handling
* Set `SDmode = 1` to use panoptic scene detection
* Set `TDmode = 1` to enable experimental text detection
* Use JSON parameter files if you want JSON-based parameter loading

#### Image quality improvements

* **Night/Dark adjustment** — improved, with shadow correction added for smoother application.
* **AI upscaling** — TensorRT improvements for up to 40% performance gain. 2x upscaling improved; new 2xFast model. Additional 4xAR model with integrated Artifact Removal. New modes: `ResizeMode 10` for 2xFast/4xFast; `ResizeMode 11` for 4xAR.
* **Artifact Removal** — improved with multi-mode handling. CPU-based `JpegSmoothQuant` and AI models combined. Modes: `Off=0`, `OnlyCPU=1`, `AutoWithAI=2`, `AutoWithAIFast=3`, `AlwaysCPU=4`, `AlwaysAI=5`, `AlwaysAIFast=6`, `AlwaysCPUandAI=7`, `AlwaysCPUandAIFast=8`.
* **Face Reconstruction** — more reliable for images with multiple faces of different sizes.
* **Background handling** — updated models. Greenscreen handling improved.

#### Detection and analysis

* **Facial Features** — facial feature vector added for face similarity and recognition tasks.
* **Scene Detection** — `SDmode = 1` based on panoptic segmentation.
* **Experimental Text Detection** — `TDmode = 1` detects areas likely to contain text.

#### Workflow and platform

* **JSON parameter files** — parameter loading now supports JSON.
* **GPU infrastructure** — updated to support CUDA 12.6.





VIESUS 11

V11 brings updates in Night/Dark adjustment, AI upscaling, facial processing, background handling, detection, and masking.

#### Requires action

* Set `Gpars/dastrength` to tune Night/Dark adjustment
* Set `srstrength`, `SRNoiseInjection`, `IsNoiseRedMode 3`, or `ISGrainAddMode` for new SR and noise controls
* Use `ResizeMode 6`, `7`, `8`, or `9` for new resize modes
* Use Small Faces, `IsFrMode 2/3`, or higher `fdstrength` for new facial options
* Activate background handling, `BGBlur`, or AutoCropping where needed
* Set `FDmode = IsFaceDetMode 3` for face anonymisation

#### Image quality improvements

* **Night/Dark adjustment** — configurable adjustments via `Gpars/dastrength` (default 0.5).
* **Improved AI upscaling** — mixed model usage for better SR results.
* **SR blending** — `srstrength` blends AI upscaling with standard upscaling.
* **New resize modes** — `ResizeMode 6` (no SR + face reconstruction), `7` (2x4x), `8` (2x4xFast), `9` (4xFast).
* **`SRNoiseInjection`** — noise injection before SR.
* **AI Noise Reduction** — `IsNoiseRedMode 3` removes noise with AI.
* **GrainAddition** — `ISGrainAddMode` adds white Gaussian noise after SR.

#### Facial processing and detection

* **Small Faces parameter** — threshold for model selection; improves SR for small faces.
* **Additional Facial Reconstruction modes** — `IsFrMode 2 (IS_FR_MIX)` and `3 (IS_FR_FAST)`.
* **Improved Face Detection** — primarily for SR. Max faces increased to 512.
* **Face Detection strength** — `fdstrength > 1.0` (e.g. 2.5) for group photos.
* **Facial Features** — eye blink and emotion estimation added.
* **Face anonymisation** — `IsFaceDetMode 3` blurs all detected faces.

#### Background handling and cropping

* **Background, Foreground, depth map** — introduced.
* **Background Handling** — removal to alpha and replacement with image or color.
* **Background Blurring** — computational bokeh via `Gpars/blurstrength` (when `BGBlur` is active).
* **Background Balancing** — introduced.
* **AutoCropping** — based on facial parameters.

#### Masks

* SDK can provide masks for foreground, background, and depth map.





VIESUS 10

V10 brings updates in AI upscaling, artifact handling, image loading, and face lighting.

#### Requires action

* Use AI upscaling as the resize method for the new SR workflow
* Enable Artifact Detection or Artifact Removal for JPEG cleanup
* Enable Adaptive Face Flash to brighten dark faces
* Use the experimental image loader if you need the added format support

#### Image quality improvements

* **AI upscaling** — now available as a separate resizing method (including Face Refinement). Requires NVIDIA GPU.
* **Artifact Detection and Artifact Removal** — Detection decides whether to apply removal. Removal reduces JPEG blocking and ringing.
* **Adaptive Face Flash** — brightens dark or back-lit faces.

#### Workflow

* **Experimental Image Loader** — loads JPEG, TIFF, PNG, WEBP, HEIC, and RAW formats.





VIESUS 9 and earlier (V9 → V7)

Combined release notes from V9.00 back to V7.00.

#### V9.00

* **Improved redeye correction** — neural network-based with better face detection. False-positive rate dramatically reduced outside facial areas.
* **Natural Skin Enhancement** — new parameter to reduce oversaturated, "glowing" faces.
* **White point adjustment for digital printing** — light grey pulled to pure white to reduce grey-dot patterns on digital prints.

#### V8.50

* **Further improved redeye correction** — large false positives in eye/nose regions considerably reduced.
* **Noise addition parameter** — reduces color banding and posterisation artifacts.
* **Adaptable processing order** — redeye reduction can run before all other corrections.
* **iOS library version** — direct integration into iOS apps.

#### V8.00

* **More stable global color and brightness correction** — more similar results across similar images.
* **Improved redeye correction** — fewer false positives.
* **Smoother redeye strength behavior** — continuous variation in detection and false-positive rates.
* **Updated ICC profile handling** — LittleCMS 2.4, fully compliant with ICC 4.3.
* **Monochrome conversion** — neutral or toned monochrome output (e.g. sepia).
* **Selectable order of resampling and enhancement** — opt in to resize-before-enhance.
* **Improved non-sRGB profile handling** — direct transform from input to output ICC profile.

#### V7.50

* **CMYK and grayscale support** — previously only RGB.
* **Viewer shadow correction** — semi-automatic manual shadow correction in the Viewer.

#### V7.35

* **Alpha channel support** — alpha data used for improved correction.
* **Smaller program footprint** — reduced code size.
* **Improved special-case handling** — corrupt image data and special ICC profiles handled better.
* **GUID licenses** — introduced for special customers.

#### V7.30

* **New license management** — software-based and dongle licenses, plus image-count-based licenses.
* **Folder Enhancer updates** — configurable JPEG compression factor, PNG input support.

#### V7.10

* **Resampling and cropping** — added with optimised algorithms for large up/downsampling.
* **Global sharpening parameter** — easier device-specific adaptation.
* **Folder Enhancer updates** — TIFF input and Unicode file name support.

#### V7.00

* **Remapped and decoupled enhancement parameters** — wider adjustment range, separate brightness and color sliders.
* **Improved redeye correction** — fewer false positives at higher detection rate.
* **Continuously adjustable redeye strength**.
* **Embedded ICC profile support** — embedded profiles in input images taken into account.
* **Output ICC profile support** — applied at the end of enhancement.
* **Automatic noise reduction** — controllable separately for color and monochrome (off by default).
* **Brighter underexposed images** — controllable via global brightness parameter.




# VIESUS Assistant

A downloadable skill that turns Claude — or another AI agent — into a VIESUS expert on your own machine: implementation, configuration, presets, error decoding, and parameter tuning.

The VIESUS Assistant is a downloadable **skill** you hand to [Claude](https://claude.com/claude-code) (or another AI agent). It packages the knowledge in this documentation (and more) so the agent can help you to operate or implement VIESUS directly — on your own machine, with your own files and commands.

{% file src="/files/08GyQVprH8Dbu2JZDHB5" %}
Last updated: August 24, 2026
{% endfile %}

***

## In-docs chat vs. the skill

These are two different things:

* **Ask AI** helps you understand VIESUS while you read. Use it for product questions, feature explanations, and quick guidance in the docs.
* **The VIESUS Assistant skill** runs **inside your own agent** (e.g. Claude Code in your terminal). Because it works where your files and tools are, it can also read your `viesusini.json`, run CLI commands, inspect result files, and iterate with you on a real workflow — not just answer questions.

***

## What it helps with

* **Answer VIESUS questions** in plain language, grounded in this documentation.
* **Guide you through installation, licensing, and your first run** for your platform and interface.
* **Build and tune a `viesusini.json` or preset** around your goals, instead of editing JSON by hand.
* **Implement VIESUS in your product or pipeline** — from a simple batch job to a full SaaS integration.
* **Create working commands or config examples** for your environment.
* **Decode errors and exit codes** and suggest the matching fix.
* **Suggest parameter changes** when results need more work.
* **Connect information across the docs** — for example, match a feature to its requirements, limits, configuration switches, and reference pages.

***

## Install & use

The skill is a zip archive containing a main skill file and supporting reference files. Download it, extract it, and make the folder available to your agent.

{% tabs %}
{% tab title="Claude Code" %}

1. Download the zip using the button above.
2. Extract it — you will get a `viesus-skill/` folder.
3. Move the folder into your Claude Code skills directory, for example:

   ```
   ~/.claude/skills/viesus-skill/
   ```
4. Start Claude Code in your project and ask it for help with VIESUS — it will use the skill automatically when relevant.
   {% endtab %}

{% tab title="Claude Desktop" %}

1. Download the zip using the button above.
2. Extract it — you will get a `viesus-skill/` folder.
3. Add the extracted folder to your Claude configuration as a skill source.
4. Ask Claude for help with VIESUS — installing, configuring, or troubleshooting.
   {% endtab %}

{% tab title="Other agents" %}
The skill uses standard skill frontmatter and plain Markdown, so any agent framework that supports skill or instruction folders can load it. Extract the zip and provide the `viesus-skill/` folder to your agent as its VIESUS knowledge source.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
The Assistant gives the best results when it can see your configuration and result files. Run it in the same environment as VIESUS so it can read `viesusini.json`, run commands, and check output.
{% endhint %}

{% hint style="warning" %}
**Experimental.** AI agents can make mistakes. Review every suggestion and keep backups.
{% endhint %}

Please report any bigger issues, problems or important knowledge gaps to [info@viesus.com](mailto:info@viesus.com?subject=VIESUS%20Assistant%20report).

Parameter	Type	Description
`fromPath`	`string`	Absolute path to the input image
`toPath`	`string`	Absolute path for the enhanced output image
`iniPath`	`string`	Absolute path to the `viesusini.json` configuration file
`resPath`	`string`	Absolute path for the result JSON output file

Code	Description
`-1`	Init failed
`-2`	GUID wrong
`-3`	Internal error
`-4`	Loading image not possible
`-5`	Can't open file
`-6`	File not found
`-7`	File is empty
`-8`	Memory open internal error
`-9`	Enhancement failed — contact info@viesus.com
`-10`	Parameter file not found
`-11`	Parameter file empty
`-12`	Output format not supported
`-13`	Error writing result file
`-126`	Enhancement failed — image was already enhanced
`-378`	Wrong GUID
`< -18`	Internal error — contact info@viesus.com

Field	Type	Description
`brightCorrStrength`	float	Applied brightness correction strength
`colorCorrStrength`	float	Applied color correction strength
`fdApplied`	int	`1` if face detection ran
`ieApplied`	int	`1` if image enhancement ran
`isArtificial`	int	`1` if image was classified as artificial/synthetic
`isMonochrome`	int	`1` if image was detected as monochrome
`locShpApplied`	int	`1` if local sharpening was applied
`rszApplied`	int	`1` if resizing was applied
`rszSRApplied`	int	`1` if AI upscaling was used for resize
`arApplied`	int	`1` if artifact removal was applied
`bgApplied`	int	`1` if background handling was applied


Docker for CLI	Build a GPU-enabled image for the `viesus` CLI and run batch jobs in a container.	Docker for CLI
Docker for Node.js	Containerize the Node.js module for a request-driven enhancement service.	Docker for Node.js

Concern	Recommendation
GUID security	Pass the GUID via an environment variable or Docker secret rather than hardcoding it in scripts
Output volume	Mount a dedicated output volume; don't write to the same path as input
Parallelism	Scale by running multiple containers (or instances) rather than more threads per instance
Image list generation	Generate the image list outside the container and mount it in; avoid running `find` inside the container
Restart policy	Use `--restart unless-stopped` for long-running hotfolder containers
Log collection	Pipe stdout/stderr to your log aggregator; the CLI writes processing results to `.res` files

Topic	Recommendation
Image size	Use multi-stage builds to reduce final image size; the CUDA runtime base is large
GUID security	Pass via environment variable or secret manager — never bake into the image
Graceful shutdown	Handle `SIGTERM` to allow in-flight requests to complete before the pool closes
Health check	Add a lightweight `GET /health` endpoint that returns 200; use it for readiness probes
Logging	Stream stdout/stderr — Docker captures it; ship to your log aggregator
GPU reservation	Use `--gpus all` or specify by device ID if only some GPUs should be used


Overview	What the Cloud API offers, when to use it vs on-premise, and the GraphQL endpoint.	Overview
Authentication	API keys, header conventions, and how to manage authentication for production.	Authentication
Uploading	Multipart upload, file size limits, supported formats, and signed URLs.	Uploading
Enhance Images	The image enhancement mutation: parameters, options, response shape, async behavior.	Enhance Images
Enhance PDFs	PDF enhancement endpoint, page selection, and result retrieval.	Enhance PDFs
Credits	How credits are consumed, free tier limits, and how to top up.	Credits
Webhooks	Async notification on enhancement completion — payload format, retries, and signing.	Webhooks

Format	MIME type	Notes
JPEG	`image/jpeg`
PNG	`image/png`
TIFF	`image/tiff`
HEIC	`image/heic`	Currently converted to JPEG after processing — this will change in a future version
WebP	`image/webp`	Currently converted to JPEG after processing — this will change in a future version
PDF	`application/pdf`	Requires analysis phase before enhancement

Scenario	Approach
SaaS product — enhance on upload	Signed upload URL → webhook on completion
Batch from existing CDN	Upload from URL in a loop → poll or webhook
PDF print workflow	Upload PDF → wait for analysis → enhance
A/B test enhancement settings	One upload → multiple `createEnhancedImage` calls
One-off manual enhancement	Dashboard UI (no API required)

Field	Description
`id`	Upload identifier — required for enhancement mutations
`status`	Upload state
`filesize`	File size in bytes
`mimetype`	Detected MIME type
`extension`	File extension
`originalFilename`	Filename as uploaded
`filename`	Storage filename
`width` / `height`	Image dimensions in pixels (0 for PDFs)
`url`	URL to access the original uploaded file
`startedAt` / `finishedAt`	Upload timestamps (ISO 8601)
`duration`	Upload processing time in milliseconds

Scenario	Calculation	Credits
All features	40÷2 + 31×1 + 9×3 = 20 + 31 + 27	78
No upscaling	20 + 31	51
No color enhancement	20 + 27	47

Use case	Why the SDK
Tight latency budget	No subprocess startup cost per image. The library stays loaded in your process.
High-frequency calls	Worth avoiding the CLI's per-call overhead when you process tens of thousands of small operations.
Existing C/C++ stack	Native linking is cleaner than shelling out to the CLI from C/C++.
Custom pipeline integration	Embed enhancement inside an existing image-processing pipeline rather than around it.
Non-C language with FFI	Any language with a C foreign-function interface (Python, Go, Rust, Java JNI, .NET P/Invoke) can call the SDK directly.

Platform	SDK availability
Windows (x64)	Supported
Linux (x64)	Supported
Linux (ARM64)	Supported
macOS	Library available — contact support
iOS	Library available since V8.50 — contact support
Android	Not currently supported


CLI Exit Codes	Exit codes from the image-enhancement engine — general, processing, scene/AI, and license/GUID errors.	CLI Exit Codes
PDF Enhancer Error Codes	Error codes from the PDF Enhancer's XML processing report — system, file-system, PDF processing, trigger, and cropping errors.	PDF Enhancer Error Codes
Node.js Error Codes	Return codes from the Node.js module — positive values are processing times in ms, negative values indicate errors.	Node.js Error Codes

Code	Description
-1	Enhancement object initialisation failed
-2	Incorrect memory organisation
-3	Enhancement validation failed
-4	Required filename parameter missing
-5	Failed to load INI/JSON configuration file
-6	Failed to save INI/JSON configuration file
-7	Invalid image pointer
-8	Invalid image data pointer
-9	Invalid processing parameters pointer
-10	Generic null pointer error
-11	Missing image enhancement analysis
-12	Failed to load ICC color profile
-13	Failed to retrieve license information
-14	Image already enhanced (use `-a` to force)
-15	Color management system analysis failed
-16	Resize analysis failed
-17	Resize region of interest out of limits
-18	Pre-processing analysis failed
-19	Face detection analysis failed
-20	Noise reduction analysis failed

Code	Description
-21	Noise reduction processing failed
-22	Red-eye reduction analysis failed
-23	Red-eye reduction processing failed
-24	Global balance processing failed
-25	Sharpening processing failed
-26	Resize processing failed (check SR model)
-27	Incorrect data type provided
-28	Red-eye region processing failed
-29	Incorrect color channel order
-30	ICC profile validation failed
-31	Memory allocation failed
-32	Color conversion to sRGB failed
-33	Color conversion from sRGB failed
-34	Operation not supported
-35	Temporary color transform failed
-36	GGA processing failed
-37	AI upscaling resize failed
-45	Face reconstruction analysis failed
-46	Face reconstruction processing failed
-47	Background analysis failed
-48	Background processing failed
-49	Face blur processing failed

Code	Description
-96	Scene-detection analysis failed
-97	Cropping failed
-98	Text-detection analysis failed
-100	AI Artifact Removal processing failed
-101	vScene preset not found
-102	vScene number invalid
-103	vScene label buffer too small

Code	Description
-50	Feature not licensed
-51	LAB feature not licensed
-52	Image limit feature not licensed
-53	Windows feature not licensed
-54	macOS feature not licensed
-55	Linux feature not licensed
-60	PDF feature not licensed
-61	TRON PDF feature not licensed
-62	V8 feature not licensed
-71	License build time error
-72	License error 1
-73	License error 2
-90 to -95	GUID license errors (wrong GUID used with the library)
-99	No license service available

Code	Description
1	An unknown or unspecified error occurred
2	The PDF file has already been enhanced (use force option to re-process)
3	Failed to load the configuration/settings file
4	Unable to open the PDF document (file may be corrupted or password-protected)
5	Failed to create required directories
6	The input file is not a valid PDF document
7	License validation failed or license is invalid
8	PDF library initialisation or operation failed

Code	Description
9	File size is below the minimum threshold for processing
12	The specified input file could not be found
14	The specified path does not exist
15	VIESUS configuration file not found
16	Destination folder does not exist or is not accessible
17	Archive folder does not exist or is not accessible
18	Debug folder does not exist or is not accessible

Photo labs & print services

Digital media & SaaS platforms

Industrial printing

Event & school photography

Image Quality

HDR Support

Native PDF Enhancement

Image Formats

AI Upscaling

Background Handling

VIESUS Cloud

VIESUS CLI

VIESUS PDF Enhancer

VIESUS Node.js Module

VIESUS C/C++ SDK

Desktop Tools

Base Enhancement

Global Color Correction

Shadow & Highlight Recovery

Noise Reduction

Sharpening

Face Detection

Face Reconstruction

Red-Eye Removal

AI Artifact Removal

AI Super Resolution

Background Handling

Background Blur

Grain Addition

Local Color Correction

Skin Tone Enhancement

Scene-Based Enhancement

HDR Tonemapping

Portrait Auto Cropping

White Fix

Adaptive Face Flash

ICC Color Management

Monochrome & Sepia

Default

vScene Enabled

AI Upscaling (full)

AI Upscaling Only

Background Removal

Background Removal + Enhance

Overview

Getting Started

API Reference

Docker for CLI

Docker for Node.js

Overview

Authentication

Uploading

Enhance Images

Enhance PDFs

Credits

Webhooks

CLI Exit Codes

PDF Enhancer Error Codes

Node.js Error Codes

Code	Description
10	Failed to save the processed file
11	Error replacing images in the PDF
21	Insufficient file permissions for the operation
22	Failed to modify file permissions
29	Unable to delete the specified file

Code	Description
19	Invalid or incorrect command-line parameters provided
20	General VIESUS processing error

Code	Description
13	PDF library failed to initialise
23	Error during PDF flattening
24	PDF color conversion failed
25	PDF flattening initialisation failed
26	Image enhancement process failed
27	Failed to read image location data from PDF
28	No corresponding PDF found for TOX file

Code	Description
30	Failed to rename the trigger file
31	Error copying folders
32	Failed to delete the trigger file
33	Unable to rename the specified folder
34	Failed to create the trigger file
35	Error during file archiving

Code	Description
37	Invalid cropping rectangle specified
38	Cropping rectangle extends beyond page boundaries
39	Error during cropping operation

Code	Description
-126	Enhancement failed — image was already enhanced
-378	Enhancement failed — wrong GUID entered