/**
 * ┌─────────────────────────────────────────────────────────────────────────┐
 * │ PAGE ANALYSIS UTILITIES - PDF Page Dimension and Layout Analysis       │
 * ├─────────────────────────────────────────────────────────────────────────┤
 * │ Filename: page-analysis-utils.ts                                        │
 * │ Language: TypeScript                                                     │
 * │ MCP Server: PDF Operations Server                                       │
 * │                                                                          │
 * │ Purpose:                                                                 │
 * │   Provides utility functions for analyzing PDF page dimensions,         │
 * │   margins, and layout properties. Includes coordinate conversion,       │
 * │   unit transformations, and margin detection algorithms.                │
 * │                                                                          │
 * │ Why this file exists:                                                   │
 * │   - Centralizes page dimension and layout calculations                  │
 * │   - Provides accurate coordinate system conversions                     │
 * │   - Enables intelligent margin detection for better positioning         │
 * │   - Supports multiple unit systems (points, inches, mm)                 │
 * │                                                                          │
 * │ Key Functions:                                                           │
 * │   - analyzePageDimensions: Extract complete page dimension info         │
 * │   - detectPageMargins: Estimate margins from content layout             │
 * │   - convertPointsToInches: Unit conversion helper                       │
 * │   - convertPointsToMM: Unit conversion helper                           │
 * │                                                                          │
 * │ Dependencies:                                                            │
 * │   - pdf-lib: PDF document manipulation and analysis                     │
 * │   - ../types: Type definitions for page analysis results                │
 * │                                                                          │
 * │ Security Considerations:                                                 │
 * │   - Validates page numbers are within document bounds                   │
 * │   - Handles malformed or corrupted PDF structures gracefully            │
 * │   - Prevents infinite loops in content analysis                         │
 * │                                                                          │
 * │ Author: PDF MCP Team                                                    │
 * │ Created: 2025-10-30                                                      │
 * │ Version: 1.0.0                                                           │
 * └─────────────────────────────────────────────────────────────────────────┘
 */
import { PDFDocument, PDFPage } from 'pdf-lib';
import type { PageDimensions, PageMargins, BoundingBox, PageAnalysisResult } from '../types.js';
/**
 * Converts points to inches
 *
 * @param points - Measurement in points
 * @returns Measurement in inches
 */
export declare function convertPointsToInches(points: number): number;
/**
 * Converts points to millimeters
 *
 * @param points - Measurement in points
 * @returns Measurement in millimeters
 */
export declare function convertPointsToMM(points: number): number;
/**
 * Converts inches to points
 *
 * @param inches - Measurement in inches
 * @returns Measurement in points
 */
export declare function convertInchesToPoints(inches: number): number;
/**
 * Converts millimeters to points
 *
 * @param mm - Measurement in millimeters
 * @returns Measurement in points
 */
export declare function convertMMToPoints(mm: number): number;
/**
 * Extracts complete page dimensions from a PDF page
 *
 * @param page - PDF page to analyze
 * @returns Complete page dimension information
 */
export declare function extractPageDimensions(page: PDFPage): PageDimensions;
/**
 * Estimates page margins based on standard document layouts and page size heuristics
 *
 * This enhanced function uses multi-tier heuristics for accurate margin detection:
 * 1. Standard page size detection (Letter, A4, Legal, etc.)
 * 2. Proportional margin calculation
 * 3. Physical edge detection using MediaBox/CropBox
 * 4. Content-aware margin refinement
 *
 * The function now properly handles:
 * - High-precision margin detection based on actual page geometry
 * - Standard document margins for all common paper sizes
 * - Custom page sizes with intelligent scaling
 * - Edge cases (extra-small, extra-large pages)
 *
 * @param dimensions - Page dimensions
 * @returns Estimated page margins with high accuracy
 */
export declare function estimateStandardMargins(dimensions: PageDimensions): PageMargins;
/**
 * Extracts MediaBox and CropBox from a PDF page
 *
 * MediaBox defines the physical page boundary
 * CropBox defines the visible area (if different from MediaBox)
 *
 * @param page - PDF page to analyze
 * @returns MediaBox and optional CropBox
 */
export declare function extractPageBoxes(page: PDFPage): {
    mediaBox: BoundingBox;
    cropBox?: BoundingBox | undefined;
};
/**
 * Analyzes a complete PDF page and returns comprehensive layout information
 *
 * @param pdfDoc - PDF document
 * @param pageNumber - Page number to analyze (1-indexed)
 * @returns Complete page analysis result
 * @throws Error if page number is invalid
 */
export declare function analyzeCompletePage(pdfDoc: PDFDocument, pageNumber: number): Promise<Omit<PageAnalysisResult, 'filePath'>>;
/**
 * Calculates the safe content area considering margins
 *
 * @param dimensions - Page dimensions
 * @param margins - Page margins
 * @returns Bounding box for safe content area
 */
export declare function calculateSafeContentArea(dimensions: PageDimensions, margins: PageMargins): BoundingBox;
/**
 * Validates if a coordinate is within page boundaries
 *
 * @param x - X coordinate
 * @param y - Y coordinate
 * @param dimensions - Page dimensions
 * @returns True if coordinate is valid
 */
export declare function isValidCoordinate(x: number, y: number, dimensions: PageDimensions): boolean;
/**
 * Normalizes coordinates to account for page rotation
 *
 * @param x - Original X coordinate
 * @param y - Original Y coordinate
 * @param dimensions - Page dimensions (including rotation)
 * @returns Normalized coordinates
 */
export declare function normalizeCoordinatesForRotation(x: number, y: number, dimensions: PageDimensions): {
    x: number;
    y: number;
};
//# sourceMappingURL=page-analysis-utils.d.ts.map