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
-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.
-h
Yes
Start in hotfolder mode
-g <guid>
Optional
Start with a specific GUID (only for GUID-licensed libraries)
Examples:
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.
Required positional arguments
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
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
-s <pages>
String
Skip specified pages (stand-alone mode only)
Page skip format:
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
-p <portNr>
Integer
12033
Port number for TraceConsumer
Image processing
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
With archive and source deletion
Skip specific pages
Analysis only
Custom resolution and resize threshold
Production batch with all options
Processing workflow
PDF opened and analyzed
Each embedded raster image is extracted
VIESUS enhancement applied (color, sharpening, noise reduction, face processing)
Optional AI upscaling to target print resolution
Enhanced images written back into the PDF structure
Enhanced PDF and XML report written to the destination
Output files
<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 resizeThresis the minimum scale factor required to trigger enhancement — below this, the image is left untouched.noResizedisables resizing entirely.
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.
Last updated
Was this helpful?
