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. The per-image enhancement parameters come from viesusini.json (the 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 or VIESUS Cloud

---

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.

viesusPDF -h [-g <guid>] [options]

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

Examples:

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

---

Stand-alone mode

Process one file or one folder of PDFs directly from the command line.

viesusPDF <source> <destFolder> <viesusIniFile> [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

viesusPDF "C:\input\document.pdf" "C:\output" "C:\config\enhance.json"

With archive and source deletion

viesusPDF "C:\input\document.pdf" "C:\output" "C:\config\enhance.json" deleteSrc archive "C:\archive"

Skip specific pages

viesusPDF "C:\input\document.pdf" "C:\output" "C:\config\enhance.json" -s "1,3,5"

Analysis only

viesusPDF "C:\input\document.pdf" "C:\output" "C:\config\enhance.json" justAnalyze

Custom resolution and resize threshold

viesusPDF "C:\input\document.pdf" "C:\output" "C:\config\enhance.json" -r 600 -T 1.5

Production batch with all options

viesusPDF "C:\batch\pdfs" "C:\enhanced" "C:\settings\config.json" deleteSrc archive "C:\backup" useSoftMasked -r 400 -T 1.3 -p 15000

---

Processing workflow

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 for the full schema.

Archive behavior

When archive <path> 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.