Struct PyramidPlanner 

pub struct PyramidPlanner { /* private fields */ }

Configuration builder for pyramid tile generation.

Holds the source image dimensions, tile size, overlap, and target layout. Call PyramidPlanner::plan to compute a complete PyramidPlan that describes every level and tile coordinate in the pyramid.

Constructing a PyramidPlanner validates all parameters up-front, so downstream code can assume the configuration is sane.

Example usage

• CLI plan command
• pdf_to_pyramid tests

Implementations

impl PyramidPlanner

pub fn new( image_width: u32, image_height: u32, tile_size: u32, overlap: u32, layout: Layout, ) -> Result<Self, PlannerError>

Create a new PyramidPlanner after validating all parameters.

Returns PlannerError if any dimension is zero, tile size is zero, or overlap is not strictly less than tile size.

pub fn with_centre(self, centre: bool) -> Self

Enable or disable centring the image within the tile grid.

pub fn plan(&self) -> PyramidPlan

Compute the full pyramid plan.

Builds every LevelPlan from level 0 (1x1) up to the full-resolution level, computing tile grid dimensions at each step. The returned PyramidPlan is a pure data structure with no side-effects; it can be queried, serialised, or handed to a tile-writing executor.

Example usage

• CLI plan command
• pdf_to_pyramid tests

pub fn estimate_peak_memory(&self) -> u64

Estimates the peak heap memory (in bytes) that generate_pyramid_observed will consume for this planner configuration.

The estimate covers the two largest allocations that coexist at peak:

1. Source raster — the caller-owned RGBA8 image passed by reference to generate_pyramid_observed. Size: image_width × image_height × 4.

2. Canvas raster — when centring is enabled, the engine embeds the source into a padded canvas before downscaling. For Google layout this canvas is square (2^z × tile_size per side) and can be significantly larger than the source. For DeepZoom/Xyz layouts the canvas is rectangular, padded to the tile grid boundary.

These two allocations coexist because the engine receives the source by shared reference (&Raster) while it allocates the canvas internally. The first downscale step frees the canvas and replaces it with a quarter-sized copy, so the peak occurs at canvas creation.

The estimate does not include PNG encoding buffers, filesystem I/O buffers, or process baseline memory — only raster pixel buffers. For container memory budgeting, add 200–500 MB of headroom on top of this value.

This method is cheap (no heap allocation, no I/O) and can be called before rendering to verify that the pipeline will fit in available memory, enabling callers to reduce DPI or reject oversized inputs before committing to an expensive render.

Examples

use libviprs::{PyramidPlanner, Layout};

let planner = PyramidPlanner::new(16820, 11888, 256, 0, Layout::Google)
    .unwrap()
    .with_centre(true);

let peak = planner.estimate_peak_memory();
// 16820×11888 → 66×47 tiles → z=7 → canvas 32768² → ~4.8 GB peak
assert!(peak > 4_000_000_000);

// Use this to gate rendering:
let memory_budget: u64 = 1_500_000_000; // 1.5 GB
if peak > memory_budget {
    // reduce DPI and retry with smaller dimensions
}

pub fn canvas_dimensions(&self) -> (u32, u32)

Computes the canvas dimensions that plan would produce, without building the full PyramidPlan.

For Google layout the canvas is square: tile_size × 2^(n_levels−1) per side. For DeepZoom/Xyz layouts the canvas is rectangular, padded to the tile grid boundary at the top level.

When centring is disabled, returns the original image dimensions (no padding).

This is a pure computation with no allocations.

Trait Implementations

impl Clone for PyramidPlanner

fn clone(&self) -> PyramidPlanner

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for PyramidPlanner

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.