pdfcrop

https://docs.rs/pdfcrop/latest
Admin
A Rust library and CLI tool for cropping PDF files with automatic bounding box detection, custom...
Tokens:77,789
Snippets:578
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### Library Usage Example

Source: https://docs.rs/pdfcrop/latest/pdfcrop/index.html

This example demonstrates how to use the pdfcrop library to crop a PDF file with specified margins.

```APIDOC
## Library Usage Example

```rust
use pdfcrop::{crop_pdf, CropOptions, BoundingBox, Margins};

let pdf_data = std::fs::read("input.pdf")?;

let options = CropOptions {
    margins: Margins::uniform(10.0),
    bbox_override: None,
    ..Default::default()
};

let cropped = crop_pdf(&pdf_data, options)?;
std::fs::write("output.pdf", cropped)?;
```
```

--------------------------------

### Basic unwrap Usage

Source: https://docs.rs/pdfcrop/latest/pdfcrop/error/type.Result.html

Demonstrates the basic usage of `unwrap` to get the value from an `Ok` variant. Panics if the `Result` is an `Err`.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.unwrap(), 2);
```

--------------------------------

### Library Usage Example

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/lib.rs.html

Demonstrates how to use the `crop_pdf` function with custom options. Reads PDF data, applies uniform margins, and writes the cropped PDF. Requires `input.pdf` to exist.

```rust
use pdfcrop::{crop_pdf, CropOptions, BoundingBox, Margins};

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let pdf_data = std::fs::read("input.pdf")?;

let options = CropOptions {
    margins: Margins::uniform(10.0),
    bbox_override: None,
    ..Default::default()
};

let cropped = crop_pdf(&pdf_data, options)?;
std::fs::write("output.pdf", cropped)?;
# Ok(())
# }
```

--------------------------------

### Example Usage of crop_pdf Function

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/crop.rs.html

Demonstrates how to use the `crop_pdf` function with custom margins. Reads a PDF, applies uniform margins, and writes the cropped PDF to a file. Requires `input.pdf` to exist.

```rust
use pdfcrop::{crop_pdf, CropOptions, Margins};

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let pdf_data = std::fs::read("input.pdf")?;
let options = CropOptions {
    margins: Margins::uniform(10.0),
    ..Default::default()
};
let cropped = crop_pdf(&pdf_data, options)?;
std::fs::write("output.pdf", cropped)?;
# Ok(())
# }
```

--------------------------------

### Handling File Metadata with `and_then`

Source: https://docs.rs/pdfcrop/latest/pdfcrop/error/type.Result.html

Demonstrates chaining fallible operations like getting file metadata and its modification time. `and_then` is useful when subsequent operations depend on the success of previous ones.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

--------------------------------

### Parse BoundingBox from string

Source: https://docs.rs/pdfcrop/latest/pdfcrop/bbox/struct.BoundingBox.html

Parses a string specification into a BoundingBox. The expected format is "left bottom right top", for example, "10 20 200 280".

```rust
pub fn from_str(s: &str) -> Result<Self>
```

--------------------------------

### Detect Bounding Box using Ghostscript

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/ghostscript.rs.html

This function uses Ghostscript's bbox device to render a PDF page and detect ink bounds. It requires the PDF data and page number as input. Ghostscript must be installed and accessible in the system's PATH. The function handles temporary file creation and cleanup.

```rust
pub fn detect_bbox_gs(pdf_data: &[u8], page_num: usize) -> Result<BoundingBox> {
    // Check if Ghostscript is available
    let gs_cmd = find_ghostscript()?;

    // Write PDF to temporary file (Ghostscript needs a file path)
    let temp_dir = std::env::temp_dir();
    let temp_pdf = temp_dir.join(format!("pdfcrop_temp_{}.pdf", std::process::id()));
    std::fs::write(&temp_pdf, pdf_data)
        .map_err(|e| Error::PdfParse(format!("failed to write temp PDF: {}", e)))?;

    // Ensure temp file is cleaned up
    let _cleanup = TempFileCleanup(&temp_pdf);

    // Run Ghostscript with bbox device
    let output = Command::new(&gs_cmd)
        .arg("-sDEVICE=bbox")
        .arg("-dBATCH")
        .arg("-dNOPAUSE")
        .arg("-dSAFER")
        .arg(format!("-dFirstPage={}", page_num + 1))
        .arg(format!("-dLastPage={}", page_num + 1))
        .arg("-q")
        .arg(&temp_pdf)
        .output()
        .map_err(|e| Error::External(format!("failed to run Ghostscript: {}", e)))?;

    if !output.status.success() {
        return Err(Error::External(format!(
            "Ghostscript exited with status: {}",
            output.status
        )));
    }

    // Ghostscript outputs bbox to stderr
    let stderr = String::from_utf8_lossy(&output.stderr);

    // Parse bbox from output
    // Format: %%BoundingBox: left bottom right top
    // or:     %%HiResBoundingBox: left bottom right top
    parse_gs_bbox_output(&stderr)
}
```

--------------------------------

### get_page_count

Source: https://docs.rs/pdfcrop/latest/pdfcrop/pdf_ops/fn.get_page_count.html

Get the number of pages in a PDF document.

```APIDOC
## get_page_count

### Description
Get the number of pages in a PDF document.

### Signature
```rust
pub fn get_page_count(doc: &Document) -> usize
```

### Parameters
* `doc` (*Document) - A reference to the PDF document.

### Returns
* `usize` - The number of pages in the document.
```

--------------------------------

### Get BoundingBox height

Source: https://docs.rs/pdfcrop/latest/pdfcrop/bbox/struct.BoundingBox.html

Calculates and returns the height of the bounding box.

```rust
pub fn height(&self) -> f64
```

--------------------------------

### Crop PDF with Custom Margins

Source: https://docs.rs/pdfcrop/latest/index.html

Demonstrates how to read PDF data, set custom crop options with uniform margins, and write the cropped PDF. Ensure 'input.pdf' exists and the output path is writable.

```rust
use pdfcrop::{crop_pdf, CropOptions, BoundingBox, Margins};

let pdf_data = std::fs::read("input.pdf")?;

let options = CropOptions {
    margins: Margins::uniform(10.0),
    bbox_override: None,
    ..Default::default()
};

let cropped = crop_pdf(&pdf_data, options)?;
std::fs::write("output.pdf", cropped)?;
```

--------------------------------

### Get BoundingBox width

Source: https://docs.rs/pdfcrop/latest/pdfcrop/bbox/struct.BoundingBox.html

Calculates and returns the width of the bounding box.

```rust
pub fn width(&self) -> f64
```

--------------------------------

### Test CropOptions with Margins

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/crop.rs.html

Demonstrates how to create `CropOptions` with specific margins applied. This test checks if uniform margins are correctly set.

```rust
#[test]
    fn test_crop_options_with_margins() {
        let options = CropOptions {
            margins: Margins::uniform(10.0),
            ..Default::default()
        };
        assert_eq!(options.margins.left, 10.0);
    }
```

--------------------------------

### Get Type Alias for Owned Type

Source: https://docs.rs/pdfcrop/latest/pdfcrop/margins/struct.Margins.html

Specifies the owned type corresponding to a borrowed type.

```rust
type Owned = T
```

--------------------------------

### Get Font Dictionary

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/content_filter.rs.html

Retrieves the font dictionary from the PDF resources. It handles both direct dictionaries and stream objects.

```rust
fn get_font_dictionary(
    doc: &Document,
    resources: Option<&Dictionary>,
    font_name: &[u8],
) -> Option<Dictionary> {
    let resources = resources?;
    let font_entry = resources.get(b"Font").ok()?;
    let font_dict_obj = resolve_to_owned(doc, font_entry)?;
    let font_dict = font_dict_obj.as_dict().ok()?;
    let font_obj = font_dict.get(font_name).ok()?.clone();
    match resolve_to_owned(doc, &font_obj)? {
        Object::Dictionary(dict) => Some(dict),
        Object::Stream(stream) => Some(stream.dict),
        _ => None,
    }
}
```

--------------------------------

### into_ok

Source: https://docs.rs/pdfcrop/latest/pdfcrop/error/type.Result.html

Returns the contained Ok value, but never panics. This is a nightly-only experimental API.

```APIDOC
## into_ok

### Description
Returns the contained `Ok` value, but never panics. Unlike `unwrap`, this method is known to never panic on the result types it is implemented for. Therefore, it can be used instead of `unwrap` as a maintainability safeguard that will fail to compile if the error type of the `Result` is later changed to an error that can actually occur.

### Method
`into_ok()`

### Parameters
None

### Request Body
None

### Request Example
```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```

### Response
#### Success Response
- `T` - The contained Ok value.

#### Response Example
```rust
// If Ok("value"), returns "value"
```

### Constraints
This is a nightly-only experimental API. Requires `E: Into<!>`.
```

--------------------------------

### BoundingBox::new

Source: https://docs.rs/pdfcrop/latest/pdfcrop/bbox/struct.BoundingBox.html

Creates a new BoundingBox instance with the specified coordinates.

```APIDOC
## `new`

```rust
pub fn new(left: f64, bottom: f64, right: f64, top: f64) -> Result<Self>
```

Create a new bounding box
```

--------------------------------

### Dereference PageRange Pointer

Source: https://docs.rs/pdfcrop/latest/pdfcrop/enum.PageRange.html

Unsafely dereferences a raw pointer to get an immutable reference to a `PageRange`. This is part of the `Pointable` trait.

```rust
unsafe fn deref<'a>(ptr: usize) -> &'a T
```

--------------------------------

### Test CropOptions Default

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/crop.rs.html

Verifies that `CropOptions` initializes with default values, including no margins, no bounding box override, and verbose mode disabled.

```rust
#[test]
    fn test_crop_options_default() {
        let options = CropOptions::default();
        assert_eq!(options.margins, Margins::none());
        assert!(options.bbox_override.is_none());
        assert!(!options.verbose);
    }
```

--------------------------------

### Get TypeId

Source: https://docs.rs/pdfcrop/latest/pdfcrop/enum.PageRange.html

Retrieves the unique `TypeId` of the `PageRange` enum. This is part of the `Any` trait implementation, useful for dynamic type checking.

```rust
fn type_id(&self) -> TypeId
```

--------------------------------

### Create a new BoundingBox

Source: https://docs.rs/pdfcrop/latest/pdfcrop/bbox/struct.BoundingBox.html

Instantiates a new BoundingBox with specified coordinates. Returns a Result, indicating potential creation failures.

```rust
pub fn new(left: f64, bottom: f64, right: f64, top: f64) -> Result<Self>
```

--------------------------------

### Mutably Dereference PageRange Pointer

Source: https://docs.rs/pdfcrop/latest/pdfcrop/enum.PageRange.html

Unsafely dereferences a raw pointer to get a mutable reference to a `PageRange`. This is part of the `Pointable` trait.

```rust
unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T
```

--------------------------------

### BoundingBox::new

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/bbox/mod.rs.html

Creates a new BoundingBox instance, ensuring that the left edge is less than the right edge and the bottom edge is less than the top edge.

```APIDOC
/// Create a new bounding box
pub fn new(left: f64, bottom: f64, right: f64, top: f64) -> Result<Self>
```

--------------------------------

### Get Form XObject ObjectId

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/content_filter.rs.html

Retrieves the ObjectId for a Form XObject by looking it up in the Resources dictionary. Handles cases where the XObject is not found or is not a dictionary.

```rust
let xobject_ref = resources.get(b"XObject")?;
    let xobject_dict = xobject_ref
        .as_dict()
        .map_err(|_| Error::PdfParse("XObject is not a dictionary".to_string()))?;

    let xobj_ref = xobject_dict
        .get(xobj_name)
        .ok()
        .and_then(|obj| obj.as_reference().ok())
        .ok_or_else(|| {
            Error::PdfParse(format!(
                "XObject {} not found in Resources",
                String::from_utf8_lossy(xobj_name)
            ))
        })?;

    Ok(xobj_ref)
```

--------------------------------

### Mutably Iterating Over `Ok` Values with `iter_mut`

Source: https://docs.rs/pdfcrop/latest/pdfcrop/error/type.Result.html

Use `iter_mut` to get a mutable iterator over the contained value. This allows modifying the `Ok` value through the iterator.

```rust
let mut x: Result<u32, &str> = Ok(7);
match x.iter_mut().next() {
    Some(v) => *v = 40,
    None => {},
}
assert_eq!(x, Ok(40));

let mut x: Result<u32, &str> = Err("nothing!");
assert_eq!(x.iter_mut().next(), None);
```

--------------------------------

### Crop PDF with Uniform Margins

Source: https://docs.rs/pdfcrop/latest/pdfcrop/crop/fn.crop_pdf.html

Reads a PDF from a file, applies uniform margins of 10.0 units to all pages using CropOptions, and writes the cropped PDF to a new file. Ensure 'input.pdf' exists and the output path is writable.

```rust
use pdfcrop::{crop_pdf, CropOptions, Margins};

let pdf_data = std::fs::read("input.pdf")?;
let options = CropOptions {
    margins: Margins::uniform(10.0),
    ..Default::default()
};
let cropped = crop_pdf(&pdf_data, options)?;
std::fs::write("output.pdf", cropped)?;
```

--------------------------------

### Unsafe Unwrapping with `unwrap_unchecked`

Source: https://docs.rs/pdfcrop/latest/pdfcrop/error/type.Result.html

Use `unwrap_unchecked` to get the `Ok` value without checking if it's an `Err`. This is unsafe and can lead to undefined behavior if called on an `Err`.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(unsafe { x.unwrap_unchecked() }, 2);
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
unsafe { x.unwrap_unchecked() }; // Undefined behavior!
```

--------------------------------

### into_ok Usage

Source: https://docs.rs/pdfcrop/latest/pdfcrop/error/type.Result.html

Illustrates `into_ok`, an experimental nightly-only API that returns the contained `Ok` value without panicking. It's a compile-time safeguard against potential panics.

```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```

--------------------------------

### Unwrapping with a Default Value using `unwrap_or`

Source: https://docs.rs/pdfcrop/latest/pdfcrop/error/type.Result.html

Use `unwrap_or` to get the `Ok` value or a provided default if the `Result` is `Err`. The default value is eagerly evaluated.

```rust
let default = 2;
let x: Result<u32, &str> = Ok(9);
assert_eq!(x.unwrap_or(default), 9);

let x: Result<u32, &str> = Err("error");
assert_eq!(x.unwrap_or(default), default);
```

--------------------------------

### Default Implementation for CropOptions

Source: https://docs.rs/pdfcrop/latest/pdfcrop/struct.CropOptions.html

Provides a default set of cropping options. This is useful for initializing CropOptions with sensible values when specific configurations are not required.

```rust
fn default() -> Self
```

--------------------------------

### Move to Next Line - Rust

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/content_filter.rs.html

Implements the T* text operator, moving the text position to the start of the next line. This is based on the current text leading value.

```rust
fn move_to_next_line(&mut self) {
        let ty = -self.leading;
        self.translate_text_line_matrix(0.0, ty);
    }
```

--------------------------------

### Create Margins: None, Uniform, and New in Rust

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/margins.rs.html

Provides methods to create `Margins` instances: `none` for zero margins, `uniform` for equal margins on all sides, and `new` for specific values on each side.

```rust
impl Margins {
    /// Create margins with all sides set to zero
    pub fn none() -> Self {
        Self {
            left: 0.0,
            top: 0.0,
            right: 0.0,
            bottom: 0.0,
        }
    }

    /// Create uniform margins (same value for all sides)
    pub fn uniform(value: f64) -> Self {
        Self {
            left: value,
            top: value,
            right: value,
            bottom: value,
        }
    }

    /// Create margins from individual values
    pub fn new(left: f64, top: f64, right: f64, bottom: f64) -> Self {
        Self {
            left,
            top,
            right,
            bottom,
        }
    }

```

--------------------------------

### Get Form XObject Reference and Resources

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/content_filter.rs.html

Retrieves the reference and optional dictionary for a Form XObject. This function is marked with #[allow(dead_code)] and is intended for later filtering operations.

```rust
let xobject_ref = resources.get(b"XObject")?;
    let xobject_dict = xobject_ref
        .as_dict()
        .map_err(|_| Error::PdfParse("XObject is not a dictionary".to_string()))?;

    let xobj_ref = xobject_dict
        .get(xobj_name)
        .ok()
        .and_then(|obj| obj.as_reference().ok())
        .ok_or_else(|| {
            Error::PdfParse(format!(
                "XObject {} not found in Resources",
                String::from_utf8_lossy(xobj_name)
            ))
        })?;

    Ok((xobj_ref, None))
```

--------------------------------

### BoundingBox implements Blanket Implementations

Source: https://docs.rs/pdfcrop/latest/pdfcrop/bbox/struct.BoundingBox.html

Shows various blanket implementations for the BoundingBox struct, including Any, Borrow, BorrowMut, CloneToUninit, From, Into, IntoEither, Pointable, Same, and ToOwned.

```rust
impl<T> Any for T
where T: 'static + ?Sized,
```

```rust
fn type_id(&self) -> TypeId
```

```rust
impl<T> Borrow<T> for T
where T: ?Sized,
```

```rust
fn borrow(&self) -> &T
```

```rust
impl<T> BorrowMut<T> for T
where T: ?Sized,
```

```rust
fn borrow_mut(&mut self) -> &mut T
```

```rust
impl<T> CloneToUninit for T
where T: Clone,
```

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

```rust
impl<T> From<T> for T
```

```rust
fn from(t: T) -> T
```

```rust
impl<T, U> Into<U> for T
where U: From<T>,
```

```rust
fn into(self) -> U
```

```rust
impl<T> IntoEither for T
```

```rust
fn into_either(self, into_left: bool) -> Either<Self, Self>
```

```rust
fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,
```

```rust
impl<T> Pointable for T
```

```rust
const ALIGN: usize
```

```rust
type Init = T
```

```rust
unsafe fn init(init: <T as Pointable>::Init) -> usize
```

```rust
unsafe fn deref<'a>(ptr: usize) -> &'a T
```

```rust
unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T
```

```rust
unsafe fn drop(ptr: usize)
```

```rust
impl<T> Same for T
```

```rust
type Output = T
```

```rust
impl<T> ToOwned for T
where T: Clone,
```

```rust
type Owned = T
```

```rust
fn to_owned(&self) -> T
```

--------------------------------

### Unsafe Unwrapping of Error with `unwrap_err_unchecked`

Source: https://docs.rs/pdfcrop/latest/pdfcrop/error/type.Result.html

Use `unwrap_err_unchecked` to get the `Err` value without checking if it's an `Ok`. This is unsafe and can lead to undefined behavior if called on an `Ok`.

```rust
let x: Result<u32, &str> = Ok(2);
unsafe { x.unwrap_err_unchecked() }; // Undefined behavior!
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
assert_eq!(unsafe { x.unwrap_err_unchecked() }, "emergency failure");
```

--------------------------------

### Lazy Unwrapping with `unwrap_or_else`

Source: https://docs.rs/pdfcrop/latest/pdfcrop/error/type.Result.html

Use `unwrap_or_else` to get the `Ok` value or compute a default value using a closure if the `Result` is `Err`. This is efficient for expensive default computations.

```rust
fn count(x: &str) -> usize { x.len() }

assert_eq!(Ok(2).unwrap_or_else(count), 2);
assert_eq!(Err("foo").unwrap_or_else(count), 3);
```

--------------------------------

### Test BoundingBox with Margins Expansion

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/bbox/mod.rs.html

Checks if the `with_margins` method correctly expands the BoundingBox by the specified uniform margins.

```rust
#[test]
fn test_bbox_with_margins() {
    use crate::margins::Margins;
    let bbox = BoundingBox::new(10.0, 20.0, 100.0, 200.0).unwrap();
    let margins = Margins::uniform(5.0);
    let expanded = bbox.with_margins(&margins);

    assert_eq!(expanded.left, 5.0);
    assert_eq!(expanded.bottom, 15.0);
    assert_eq!(expanded.right, 105.0);
    assert_eq!(expanded.top, 205.0);
}
```

--------------------------------

### pub fn ok(self) -> Option<T>

Source: https://docs.rs/pdfcrop/latest/pdfcrop/error/type.Result.html

Converts a Result<T, E> into an Option<T>, consuming the original Result and discarding any error value.

```APIDOC
## pub fn ok(self) -> Option<T>

### Description
Converts `self` into an `Option<T>`, consuming `self`, and discarding the error, if any.

### Method
`self.ok()`

### Parameters
None

### Request Body
None

### Request Example
```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.ok(), Some(2));

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.ok(), None);
```

### Response
#### Success Response (Option<T>)
- Returns `Some(T)` if the original Result was `Ok(T)`.
- Returns `None` if the original Result was `Err(E)`.

#### Response Example
```rust
// For Ok(2), returns Some(2)
// For Err("Nothing here"), returns None
```
```

--------------------------------

### Get PDF Page Count

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/pdf_ops.rs.html

Retrieves the total number of pages in a given PDF document. This function is straightforward and relies on the `Document`'s internal page count.

```rust
/// Get the number of pages in a PDF document
pub fn get_page_count(doc: &Document) -> usize {
    doc.get_pages().len()
}
```

--------------------------------

### Create a new BoundingBox

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/bbox/mod.rs.html

Creates a new BoundingBox instance. Ensures that the left edge is less than the right edge, and the bottom edge is less than the top edge.

```rust
pub fn new(left: f64, bottom: f64, right: f64, top: f64) -> Result<Self> {
        if left >= right {
            return Err(Error::InvalidBoundingBox(format!(
                "left ({}) must be less than right ({})",
                left,
                right
            )));
        }
        if bottom >= top {
            return Err(Error::InvalidBoundingBox(format!(
                "bottom ({}) must be less than top ({})",
                bottom,
                top
            )));
        }

        Ok(Self {
            left,
            bottom,
            right,
            top,
        })
    }
```

--------------------------------

### Get Page MediaBox Dimensions

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/pdf_ops.rs.html

Retrieves the MediaBox dimensions (width and height) for a specified page in a PDF document. It handles errors if the page is not found or if the MediaBox is malformed.

```rust
let page_id = doc
        .page_iter()
        .nth(page_num)
        .ok_or_else(|| Error::InvalidPage(format!("page {} not found", page_num)))?;
```

```rust
let page = doc
        .get_object(page_id)
        .map_err(|e| Error::PdfParse(format!("failed to get page {}: {}", page_num, e)))?
        .as_dict()
        .map_err(|e| Error::PdfParse(format!("page {} is not a dictionary: {}", page_num, e)))?;
```

```rust
let media_box = page
        .get(b"MediaBox")
        .map_err(|e| Error::PdfParse(format!("MediaBox not found: {}", e)))?
        .as_array()
        .map_err(|e| Error::PdfParse(format!("MediaBox is not an array: {}", e)))?;
```

```rust
if media_box.len() != 4 {
        return Err(Error::PdfParse(format!(
            "MediaBox has wrong length: {}",
            media_box.len()
        )));
    }
```

--------------------------------

### Applying Crop Boxes Sequentially

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/crop.rs.html

Iterates through the detected bounding box results and applies the cropbox to each page. This operation mutates the document and must be done sequentially.

```rust
for (page_num, bbox_result) in bbox_results.iter() {
    // Extract bbox from result (propagate errors)
    let (final_bbox, is_manual) = bbox_result.as_ref().map_err(|e| {
        Error::PdfParse(format!(
            "Failed to detect bbox for page {}: {}",
            page_num + 1,
            e
        ))
    })?;

    // Apply content filtering if enabled and bbox was manually specified
    // Now supports recursive Form XObject filtering
    let should_clip = options.clip_content && *is_manual;

    #[cfg(target_arch = "wasm32")]
    {
        use wasm_bindgen::JsValue;
        if options.clip_content {
            if *is_manual {
                web_sys::console::log_1(&JsValue::from_str(&format!(
                    "[DEBUG] Page {}: Applying content clipping (manual bbox)",
                    page_num + 1
                )));
            } else {
                web_sys::console::log_1(&JsValue::from_str(&format!(
                    "[DEBUG] Page {}: Skipping clipping (auto-detected bbox - already tight)",

```

--------------------------------

### BBoxMethod Enum Definition

Source: https://docs.rs/pdfcrop/latest/pdfcrop/enum.BBoxMethod.html

Defines the available methods for bounding box detection. Use Ghostscript for accuracy if installed, ContentStream for a pure Rust solution, or Auto to try Ghostscript first.

```rust
pub enum BBoxMethod {
    Ghostscript,
    ContentStream,
    Auto,
}
```

--------------------------------

### and Method Usage

Source: https://docs.rs/pdfcrop/latest/pdfcrop/error/type.Result.html

Demonstrates the `and` method, which returns the second `Result` if the first is `Ok`, otherwise returns the `Err` of the first. Arguments are eagerly evaluated.

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("late error"));
```

```rust
let x: Result<u32, &str> = Err("early error");
let y: Result<&str, &str> = Ok("foo");
assert_eq!(x.and(y), Err("early error"));
```

```rust
let x: Result<u32, &str> = Err("not a 2");
let y: Result<&str, &str> = Err("late error");
assert_eq!(x.and(y), Err("not a 2"));
```

```rust
let x: Result<u32, &str> = Ok(2);
let y: Result<&str, &str> = Ok("different result type");
assert_eq!(x.and(y), Ok("different result type"));
```

--------------------------------

### Clone Implementation for CropOptions

Source: https://docs.rs/pdfcrop/latest/pdfcrop/struct.CropOptions.html

Provides the ability to create a deep copy of CropOptions. This is useful for modifying cropping settings without affecting the original configuration.

```rust
fn clone(&self) -> CropOptions
```

--------------------------------

### Component-based Filtering Initialization

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/content_filter.rs.html

Parses PDF content operations into filterable components. This is a new approach for more granular content manipulation.

```rust
// NEW: Component-based filtering
    // Parse operations into filterable components
    let components = parse_into_components(doc, &content.operations, resources)?;
```

--------------------------------

### Compare BoundingBoxes for equality

Source: https://docs.rs/pdfcrop/latest/pdfcrop/bbox/struct.BoundingBox.html

Implements PartialEq for BoundingBox, enabling equality checks between two bounding boxes.

```rust
fn eq(&self, other: &BoundingBox) -> bool
```

```rust
fn ne(&self, other: &Rhs) -> bool
```

--------------------------------

### Get MediaBox from PDF Page Dictionary

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/bbox/mod.rs.html

Extracts the MediaBox from a PDF page dictionary. Handles potential errors like missing keys or incorrect types. The MediaBox defines the physical boundaries of the page.

```rust
pub(crate) fn get_media_box(page: &lopdf::Dictionary) -> Result<BoundingBox> {
    let media_box = page
        .get(b"MediaBox")
        .map_err(|e| Error::PdfParse(format!("MediaBox not found: {}", e)))?;

    let media_box = media_box
        .as_array()
        .map_err(|e| Error::PdfParse(format!("MediaBox is not an array: {}", e)))?;

    if media_box.len() != 4 {
        return Err(Error::PdfParse(format!("MediaBox has wrong length: {}",
            media_box.len()
        )));
    }

    // MediaBox values can be either Integer or Real
    let left = media_box[0]
        .as_f32()
        .map(|f| f as f64)
        .or_else(|_| media_box[0].as_i64().map(|i| i as f64))
        .map_err(|e| Error::PdfParse(format!("invalid MediaBox left: {}", e)))?;
    let bottom = media_box[1]
        .as_f32()
        .map(|f| f as f64)
        .or_else(|_| media_box[1].as_i64().map(|i| i as f64))
        .map_err(|e| Error::PdfParse(format!("invalid MediaBox bottom: {}", e)))?;
    let right = media_box[2]
        .as_f32()
        .map(|f| f as f64)
        .or_else(|_| media_box[2].as_i64().map(|i| i as f64))
        .map_err(|e| Error::PdfParse(format!("invalid MediaBox right: {}", e)))?;
    let top = media_box[3]
        .as_f32()
        .map(|f| f as f64)
        .or_else(|_| media_box[3].as_i64().map(|i| i as f64))
        .map_err(|e| Error::PdfParse(format!("invalid MediaBox top: {}", e)))?;

    BoundingBox::new(left, bottom, right, top)
}
```

--------------------------------

### Determining Pages to Process

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/crop.rs.html

Selects the pages to be processed based on the `page_range` option, or defaults to all pages if `page_range` is not specified.

```rust
let pages_to_process: Vec<usize> = if let Some(ref range) = options.page_range {
    range.to_page_list(page_count)
} else {
    (0..page_count).collect()
};
```

--------------------------------

### Handle Text Line Start Operator T* in PDF Content

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/content_filter.rs.html

Processes the T* operator to move the text cursor to the beginning of the next line. This is a simple operator that affects text flow within a text object.

```rust
"T*" => {
                // Move to start of next line
                state.move_to_next_line();
                graphics_state_ops.push(op.clone());
            }
```

--------------------------------

### Calculate Bounding Box from Points

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/content_filter.rs.html

Calculates the minimum and maximum X and Y coordinates from a list of points to define a bounding box. Returns an Option<BoundingBox>.

```rust
    let min_x = points
        .iter()
        .map(|(x, _)| x)
        .fold(f64::INFINITY, |a, &b| a.min(b));
    let max_x = points
        .iter()
        .map(|(x, _)| x)
        .fold(f64::NEG_INFINITY, |a, &b| a.max(b));
    let min_y = points
        .iter()
        .map(|(_, y)| y)
        .fold(f64::INFINITY, |a, &b| a.min(b));
    let max_y = points
        .iter()
        .map(|(_, y)| y)
        .fold(f64::NEG_INFINITY, |a, &b| a.max(b));

    BoundingBox::new(min_x, min_y, max_x, max_y).ok()
```

--------------------------------

### Find Ghostscript Executable

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/ghostscript.rs.html

This function searches for the Ghostscript executable in the system's PATH by trying common command names. It returns the command name if found, otherwise an error indicating Ghostscript is not installed.

```rust
fn find_ghostscript() -> Result<String> {
    // Try common Ghostscript command names
    let candidates = vec!["gs", "gswin64c", "gswin32c", "gsc"];

    for cmd in candidates {
        if Command::new(cmd)
            .arg("--version")
            .output()
            .map(|o| o.status.success())
            .unwrap_or(false)
        {
            return Ok(cmd.to_string());
        }
    }

    Err(Error::External(
        "Ghostscript not found. Please install Ghostscript:\n\         - macOS: brew install ghostscript\n\         - Ubuntu/Debian: sudo apt-get install ghostscript\n\         - Windows: download from https://www.ghostscript.com/"
            .to_string(),
    ))
}
```

--------------------------------

### Save and Restore Graphics State

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/content_filter.rs.html

Handles the 'q' (save state) and 'Q' (restore state) operators. 'q' pushes the current graphics state onto a stack, and 'Q' pops it, restoring the previous state.

```rust
"q" => {
    state_stack.push(state.clone());
    graphics_state_ops.push(op.clone());
}
"Q" => {
    if let Some(saved_state) = state_stack.pop() {
        state = saved_state;
    }
    graphics_state_ops.push(op.clone());
}
```

--------------------------------

### Test Create Clipping Path Operations (Rust)

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/content_filter.rs.html

Verifies the correct generation of clipping path operations for a given bounding box. Asserts the number and type of operations produced.

```rust
    #[test]
    fn test_create_clipping_path() {
        let bbox = BoundingBox::new(100.0, 100.0, 500.0, 700.0).unwrap();
        let ops = create_clipping_path_operations(&bbox);
        assert_eq!(ops.len(), 4);
        assert_eq!(ops[0].operator, "q");
        assert_eq!(ops[1].operator, "re");
        assert_eq!(ops[2].operator, "W");
        assert_eq!(ops[3].operator, "n");
    }
```

--------------------------------

### Getting a Mutable Reference with as_mut()

Source: https://docs.rs/pdfcrop/latest/pdfcrop/error/type.Result.html

The `as_mut()` method converts a `&mut Result<T, E>` into a `Result<&mut T, &mut E>`, providing mutable references to the contained values. This allows in-place modification of the success or error value.

```rust
fn mutate(r: &mut Result<i32, i32>) {
    match r.as_mut() {
        Ok(v) => *v = 42,
        Err(e) => *e = 0,
    }
}

let mut x: Result<i32, i32> = Ok(2);
mutate(&mut x);
assert_eq!(x.unwrap(), 42);

let mut x: Result<i32, i32> = Err(13);
mutate(&mut x);
assert_eq!(x.unwrap_err(), 0);
```

--------------------------------

### Structs

Source: https://docs.rs/pdfcrop/latest/pdfcrop

This section details the structs available in the pdfcrop crate.

```APIDOC
## Structs

`CropOptions`
    Options for PDF cropping operations
```

--------------------------------

### Getting a Reference to the Result Content with as_ref()

Source: https://docs.rs/pdfcrop/latest/pdfcrop/error/type.Result.html

The `as_ref()` method converts a `&Result<T, E>` into a `Result<&T, &E>`, providing immutable references to the contained values without consuming the original Result. This is useful for inspecting the contents of a Result without taking ownership.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.as_ref(), Ok(&2));

let x: Result<u32, &str> = Err("Error");
assert_eq!(x.as_ref(), Err(&"Error"));
```

--------------------------------

### impl<T, E> Result<Option<T>, E>

Source: https://docs.rs/pdfcrop/latest/pdfcrop/error/type.Result.html

Implementation for `Result<Option<T>, E>` providing the `transpose` method.

```APIDOC
## impl<T, E> Result<Option<T>, E>

### transpose

Transposes a `Result` of an `Option` into an `Option` of a `Result`. `Ok(None)` will be mapped to `None`. `Ok(Some(_))` and `Err(_)` will be mapped to `Some(Ok(_))` and `Some(Err(_))` respectively.

#### Signature

```rust
pub const fn transpose(self) -> Option<Result<T, E>>
```

#### Examples

```rust
#[derive(Debug, Eq, PartialEq)]
struct SomeErr;

let x: Result<Option<i32>, SomeErr> = Ok(Some(5));
let y: Option<Result<i32, SomeErr>> = Some(Ok(5));
assert_eq!(x.transpose(), y);
```
```

--------------------------------

### Loading PDF Document

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/crop.rs.html

Loads the PDF data into a `lopdf::Document` object for further processing.

```rust
let mut doc = Document::load_mem(pdf_data)?;
```

--------------------------------

### Create Margins with Zero Values

Source: https://docs.rs/pdfcrop/latest/pdfcrop/margins/struct.Margins.html

Initializes a Margins struct with all margin values set to zero.

```rust
pub fn none() -> Self
```

--------------------------------

### Test BoundingBox Creation and Validation

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/bbox/mod.rs.html

Tests the creation of a BoundingBox with valid coordinates and checks for invalid cases where right is less than left or top is less than bottom.

```rust
#[test]
fn test_bbox_new() {
    let bbox = BoundingBox::new(10.0, 20.0, 100.0, 200.0).unwrap();
    assert_eq!(bbox.left, 10.0);
    assert_eq!(bbox.bottom, 20.0);
    assert_eq!(bbox.right, 100.0);
    assert_eq!(bbox.top, 200.0);
}

#[test]
fn test_bbox_invalid() {
    assert!(BoundingBox::new(100.0, 20.0, 10.0, 200.0).is_err());
    assert!(BoundingBox::new(10.0, 200.0, 100.0, 20.0).is_err());
}
```

--------------------------------

### Initialize PageRange Pointer

Source: https://docs.rs/pdfcrop/latest/pdfcrop/enum.PageRange.html

Unsafely initializes memory at a given pointer to represent a `PageRange`. This is part of the `Pointable` trait and requires careful handling.

```rust
unsafe fn init(init: <T as Pointable>::Init) -> usize
```

--------------------------------

### Converting Result to Option with ok()

Source: https://docs.rs/pdfcrop/latest/pdfcrop/error/type.Result.html

The `ok()` method consumes the Result and returns an Option containing the success value if it's Ok, or None if it's Err. This is useful for discarding errors when only the success value is of interest.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(x.ok(), Some(2));

let x: Result<u32, &str> = Err("Nothing here");
assert_eq!(x.ok(), None);
```

--------------------------------

### BoundingBox::from_str

Source: https://docs.rs/pdfcrop/latest/pdfcrop/bbox/struct.BoundingBox.html

Parses a BoundingBox from a string specification.

```APIDOC
## `from_str`

```rust
pub fn from_str(s: &str) -> Result<Self>
```

Parse bounding box from string specification
Format: “left bottom right top” Example: “10 20 200 280”
```

--------------------------------

### Test BoundingBox Parsing from String

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/bbox/mod.rs.html

Tests the ability to create a BoundingBox from a space-separated string of coordinates.

```rust
#[test]
fn test_bbox_from_str() {
    let bbox = BoundingBox::from_str("10 20 100 200").unwrap();
    assert_eq!(bbox.left, 10.0);
    assert_eq!(bbox.bottom, 20.0);
    assert_eq!(bbox.right, 100.0);
    assert_eq!(bbox.top, 200.0);
}
```

--------------------------------

### Debug Logging for Manual BBox - Wasm

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/crop.rs.html

Logs the manual bounding box details and shrink-to-content option when running in a WebAssembly environment.

```rust
#[cfg(target_arch = "wasm32")]
{
    use wasm_bindgen::JsValue;
    web_sys::console::log_1(&JsValue::from_str(&format!(
        "[DEBUG] Manual bbox for page {}: ({:.2}, {:.2}, {:.2}, {:.2}), shrink_to_content: {}",
        page_num + 1, bbox.left, bbox.bottom, bbox.right, bbox.top, options.shrink_to_content
    )));
}
```

--------------------------------

### Main crop_pdf Function Signature

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/crop.rs.html

The public function for cropping PDF data. It takes raw PDF bytes and crop options, returning the processed PDF bytes or an error.

```rust
pub fn crop_pdf(pdf_data: &[u8], options: CropOptions) -> Result<Vec<u8>>
```

--------------------------------

### WASM Debug Logging for Page Count

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/crop.rs.html

Conditional logging for WebAssembly targets to display the total number of pages in the loaded PDF document.

```rust
#[cfg(target_arch = "wasm32")]
{
    use wasm_bindgen::JsValue;
    web_sys::console::log_1(&JsValue::from_str(&format!(
        "[DEBUG] Total pages in document: {}",
        page_count
    )));
}
```

--------------------------------

### Product aggregation with Result

Source: https://docs.rs/pdfcrop/latest/pdfcrop/error/type.Result.html

Use the `product` method to compute the product of elements in an iterator where each element is a `Result`. If any element is an `Err`, the aggregation stops and returns that `Err`. Otherwise, it returns the `Ok` value of the product.

```rust
let nums = vec!["5", "10", "1", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert_eq!(total, Ok(100));
```

```rust
let nums = vec!["5", "10", "one", "2"];
let total: Result<usize, _> = nums.iter().map(|w| w.parse::<usize>()).product();
assert!(total.is_err());
```

--------------------------------

### TryFrom Trait

Source: https://docs.rs/pdfcrop/latest/pdfcrop/struct.CropOptions.html

Enables attempting conversions from one type to another, returning a Result.

```APIDOC
## impl<T, U> TryFrom<U> for T
where U: Into<T>,

### type Error = Infallible
The type returned in the event of a conversion error.

### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>
Performs the conversion.
```

--------------------------------

### BoundingBox implements StructuralPartialEq

Source: https://docs.rs/pdfcrop/latest/pdfcrop/bbox/struct.BoundingBox.html

Indicates that BoundingBox implements StructuralPartialEq for structural equality comparisons.

```rust
impl StructuralPartialEq for BoundingBox
```

--------------------------------

### Clone to Uninitialized Memory (Nightly)

Source: https://docs.rs/pdfcrop/latest/pdfcrop/margins/struct.Margins.html

Experimental nightly-only API to perform copy-assignment to uninitialized memory.

```rust
unsafe fn clone_to_uninit(&self, dest: *mut u8)
```

--------------------------------

### Test BoundingBox Dimensions Calculation

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/bbox/mod.rs.html

Verifies the calculation of width and height for a BoundingBox instance.

```rust
#[test]
fn test_bbox_dimensions() {
    let bbox = BoundingBox::new(10.0, 20.0, 110.0, 220.0).unwrap();
    assert_eq!(bbox.width(), 100.0);
    assert_eq!(bbox.height(), 200.0);
}
```

--------------------------------

### Render Bounding Box in Rust

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/bbox/render.rs.html

Converts pixel coordinates (min_x, max_x, min_y, max_y) and image dimensions (width, height) with a given scale into a PDF BoundingBox. It handles the y-axis flip where pixel y=0 corresponds to PDF y=height.

```rust
let left = (min_x as f32) / scale;
    let right = (max_x as f32 + 1.0) / scale; // +1 because max_x is inclusive

    // Flip y-axis: pixmap y=0 is PDF y=height
    let pdf_height = (height as f32) / scale;
    let bottom = pdf_height - ((max_y as f32 + 1.0) / scale);
    let top = pdf_height - ((min_y as f32) / scale);

    BoundingBox::new(left as f64, bottom as f64, right as f64, top as f64)
}
```

--------------------------------

### Margins::uniform(value: f64)

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/margins.rs.html

Creates a Margins instance with a uniform value applied to all sides.

```APIDOC
/// Create uniform margins (same value for all sides)
pub fn uniform(value: f64) -> Self {
    Self {
        left: value,
        top: value,
        right: value,
        bottom: value,
    }
}
```

--------------------------------

### Margins::new(left: f64, top: f64, right: f64, bottom: f64)

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/margins.rs.html

Creates a Margins instance with individual values for each side.

```APIDOC
/// Create margins from individual values
pub fn new(left: f64, top: f64, right: f64, bottom: f64) -> Self {
    Self {
        left,
        top,
        right,
        bottom,
    }
}
```

--------------------------------

### Handle Clipping Path Operators

Source: https://docs.rs/pdfcrop/latest/src/pdfcrop/content_filter.rs.html

Processes PDF clipping path operators ('W', 'W*') by adding them to the path buffer. These operators define clipping regions for subsequent content.

```rust
// Clipping operators - add to path buffer
            "W" | "W*" => {
                path_buffer.push(op.clone());
            }
```
Tokens:
Raw