libviprs 0.3.0

A pure-Rust, thread-safe image pyramiding engine. Inspired by libvips, built from scratch for the AEC/construction domain.

Takes blueprint PDFs and images, extracts raster data, optionally geo-references it, and generates tile pyramids (DeepZoom, XYZ, Google Maps) suitable for web-based viewers.

Features

• PDF extraction — extract embedded raster images from scanned blueprint PDFs via lopdf (pure Rust, no C dependencies)
• PDF rendering — render vector PDFs (AutoCAD exports, text, paths) via PDFium, with optional memory-budgeted rendering (optional pdfium feature)
• Image decoding — JPEG, PNG, TIFF via the image crate
• Tile pyramid generation — multi-threaded engine with backpressure, configurable tile size and overlap
• Layout formats — DeepZoom (.dzi + directory tree), XYZ (z/x/y), and Google Maps (z/y/x, power-of-2 grids)
• Centre support — centre image within the tile grid with even background padding on all sides
• Tile encoding — PNG, JPEG (configurable quality), or raw pixel output
• Blank tile optimization — configurable BlankTileStrategy to either emit full tiles or write 1-byte placeholders (BLANK_TILE_MARKER) for uniform-color regions, reducing disk usage for sparse images
• Edge tile background — configurable background color (background_rgb) for padding partial tiles at image edges (defaults to white)
• Geo-referencing — affine transform mapping pixel coordinates to geographic coordinates, GCP support
• Observability — progress events, per-level callbacks, peak memory tracking

Usage

use libviprs::{
    extract_page_image, generate_pyramid, BlankTileStrategy,
    EngineConfig, FsSink, Layout, PyramidPlanner, TileFormat,
};
use std::path::Path;

// Extract raster from a scanned blueprint PDF
let raster = extract_page_image(Path::new("blueprint.pdf"), 1).unwrap();

// Plan the pyramid
let planner = PyramidPlanner::new(
    raster.width(), raster.height(),
    256,  // tile size
    0,    // overlap
    Layout::DeepZoom,
).unwrap();
let plan = planner.plan();

// Generate tiles to disk
let sink = FsSink::new("output_tiles", plan.clone(), TileFormat::Png);
let config = EngineConfig::default()
    .with_concurrency(4)
    .with_blank_tile_strategy(BlankTileStrategy::Placeholder);
let result = generate_pyramid(&raster, &plan, &sink, &config).unwrap();

println!(
    "{} tiles across {} levels ({} blank tiles skipped)",
    result.tiles_produced, result.levels_processed, result.tiles_skipped,
);

Modules

Features

Requirements

• Rust 1.85+ (edition 2024)
• libpdfium shared library (only if using the pdfium feature)

PDFium setup

The pdfium feature requires libpdfium.so at runtime. Pre-compiled binaries built from source are available from libviprs-dep:

# x86_64
curl -L -o pdfium.tgz \
  https://github.com/libviprs/libviprs-dep/releases/download/pdfium-7725/pdfium-linux-x64.tgz

# arm64
curl -L -o pdfium.tgz \
  https://github.com/libviprs/libviprs-dep/releases/download/pdfium-7725/pdfium-linux-arm64.tgz

# Extract and install
tar xzf pdfium.tgz
sudo cp pdfium-linux-*/lib/libpdfium.so /usr/local/lib/
sudo ldconfig

See the libviprs-dep pdfium README for building PDFium from source or finding other versions.

Related Crates

CI

GitHub Actions runs two workflows:

CI (every push and PR) — .github/workflows/ci.yml:

• cargo fmt --check — formatting
• cargo clippy -D warnings — lint (default + pdfium feature)
• cargo test — unit tests

Merge Gate (PRs targeting release, required to merge) — .github/workflows/merge-gate.yml:

• cargo +nightly miri test — undefined behavior detection
• Loom concurrency tests

Running CI locally

A Makefile mirrors the full CI pipeline. Run everything with:

make ci

Or run individual checks:

make fmt      # check formatting
make clippy   # clippy (default + pdfium features)
make test     # unit tests
make miri     # miri (requires nightly + miri component)
make loom     # loom concurrency tests

Prerequisites: make miri requires the nightly toolchain with the miri component. Install with: rustup toolchain install nightly --component miri