Configuration Tuning Guide

Configuration Tuning Guide

Complete reference for all configuration parameters.

ConversionConfig Overview

from conversion.models import (
    ConversionConfig,
    PageRanges,
    ExcludeRegions,
    MultiColumnConfig,
    HeadingConfig,
    FootnoteConfig,
    ImageOptimizationConfig,
    BookMetadata,
)

config = ConversionConfig(
    page_ranges=PageRanges(...),
    exclude_regions=ExcludeRegions(...),
    multi_column=MultiColumnConfig(...),
    reading_order_strategy="y_sort",
    heading_detection=HeadingConfig(...),
    footnote_processing=FootnoteConfig(...),
    image_optimization=ImageOptimizationConfig(...),
    metadata=BookMetadata(...),
)

PageRanges

Controls which pages to process.

@dataclass
class PageRanges:
    skip: List[int] = field(default_factory=list)
    content: Tuple[int, int] = (1, -1)
    endnotes: Optional[Tuple[int, int]] = None

Parameters

Examples

# Skip title and copyright pages (1-2), content from 3 to third-from-last
PageRanges(
    skip=[1, 2],
    content=(3, -3),
    endnotes=(-2, -1)  # Last 2 pages are endnotes
)

# Process entire document
PageRanges(content=(1, -1))

# Skip specific pages (index, ads, etc.)
PageRanges(skip=[1, 2, 50, 51, 100])

ExcludeRegions

Defines areas to exclude from each page (headers, footers, margins).

@dataclass
class ExcludeRegions:
    top: float = 0.0
    bottom: float = 0.0
    left: float = 0.0
    right: float = 0.0

Parameters

Examples

# Standard header/footer exclusion
ExcludeRegions(top=0.05, bottom=0.05)

# Aggressive exclusion for PDFs with large headers
ExcludeRegions(top=0.08, bottom=0.08)

# Side margins for bound books with gutter
ExcludeRegions(left=0.05, right=0.02)

# No exclusion (use all content)
ExcludeRegions()  # All zeros

Tuning Tips

• Start with 0.05 (5%) for top/bottom
• If page numbers still appear → increase to 0.08
• If content is cut off → decrease to 0.03
• Visual inspection: Open PDF and measure header height as % of page

MultiColumnConfig

Controls multi-column layout detection.

@dataclass
class MultiColumnConfig:
    enabled: bool = False
    column_count: int = 1
    threshold: float = 0.4

Parameters

Examples

# Standard 2-column academic paper
MultiColumnConfig(enabled=True, column_count=2, threshold=0.4)

# Magazine with variable columns
MultiColumnConfig(enabled=True, threshold=0.3)

# Disable column detection (single column)
MultiColumnConfig(enabled=False)

Tuning Tips

• If columns not detected: Lower threshold to 0.3
• If false positives (seeing columns where there are none): Raise to 0.5
• Set column_count if you know the exact layout

reading_order_strategy

Selects the algorithm for ordering text blocks.

reading_order_strategy: str = "y_sort"  # or "xy_cut"

Options

Examples

# Fiction book (single column)
reading_order_strategy="y_sort"

# Academic paper (2 columns)
reading_order_strategy="xy_cut"

# Magazine with mixed layout
reading_order_strategy="xy_cut"

HeadingConfig

Controls heading detection heuristics.

@dataclass
class HeadingConfig:
    font_size_threshold: float = 1.2
    max_heading_levels: int = 3

Parameters

Examples

# Standard threshold (20% larger = heading)
HeadingConfig(font_size_threshold=1.2)

# Detect smaller headings (10% larger)
HeadingConfig(font_size_threshold=1.1)

# Only detect major headings (30% larger)
HeadingConfig(font_size_threshold=1.3)

# Limit to 2 heading levels
HeadingConfig(max_heading_levels=2)

Tuning Tips

• If headings missed: Lower threshold to 1.1
• If regular text marked as headings: Raise to 1.3
• Check font size distribution in PDF to determine ideal threshold

FootnoteConfig

Controls footnote/endnote processing.

@dataclass
class FootnoteConfig:
    enabled: bool = False
    patterns: List[str] = field(default_factory=list)
    generate_backlinks: bool = True

Parameters

Built-in Patterns

The detector automatically finds:

• [1], [12] (bracket style)
• (1), (12) (parenthesis style)
• .1, .12 (period style)
• word1, word12 (superscript-like)

Examples

# Enable with defaults
FootnoteConfig(enabled=True)

# Add custom pattern
FootnoteConfig(
    enabled=True,
    patterns=[r'\*(\d+)']  # Matches *1, *2, etc.
)

# No backlinks
FootnoteConfig(enabled=True, generate_backlinks=False)

ImageOptimizationConfig

Controls image processing for EPUB.

@dataclass
class ImageOptimizationConfig:
    enabled: bool = True
    max_width: int = 1200
    max_height: int = 1600
    jpeg_quality: int = 85
    convert_png_to_jpeg: bool = False

Parameters

Examples

# High quality (larger files)
ImageOptimizationConfig(
    max_width=1600,
    jpeg_quality=95
)

# Optimized for mobile (smaller files)
ImageOptimizationConfig(
    max_width=800,
    max_height=1000,
    jpeg_quality=75,
    convert_png_to_jpeg=True
)

# Disable optimization (keep original)
ImageOptimizationConfig(enabled=False)

Tuning Tips

• E-reader screens are typically 1200x1600, larger images waste space
• JPEG quality 85 is visually lossless for most images
• convert_png_to_jpeg=True significantly reduces file size but loses transparency

BookMetadata

Metadata for the EPUB file.

@dataclass
class BookMetadata:
    title: Optional[str] = None
    author: Optional[str] = None
    language: str = "en"
    publisher: Optional[str] = None
    isbn: Optional[str] = None
    description: Optional[str] = None

Parameters

Examples

# Auto-extract from PDF
BookMetadata()

# Override title and author
BookMetadata(
    title="My Book",
    author="John Doe"
)

# Full metadata
BookMetadata(
    title="Complete Guide",
    author="Jane Smith",
    language="en",
    publisher="Tech Books Inc",
    isbn="978-1234567890",
    description="A comprehensive guide to..."
)

Complete Configuration Example

config = ConversionConfig(
    page_ranges=PageRanges(
        skip=[1, 2],
        content=(3, -3),
        endnotes=(-2, -1)
    ),
    exclude_regions=ExcludeRegions(
        top=0.05,
        bottom=0.05
    ),
    multi_column=MultiColumnConfig(
        enabled=False
    ),
    reading_order_strategy="y_sort",
    heading_detection=HeadingConfig(
        font_size_threshold=1.2,
        max_heading_levels=3
    ),
    footnote_processing=FootnoteConfig(
        enabled=True,
        generate_backlinks=True
    ),
    image_optimization=ImageOptimizationConfig(
        enabled=True,
        max_width=1200,
        jpeg_quality=85
    ),
    metadata=BookMetadata(
        title="My Book",
        author="Author Name",
        language="en"
    )
)

Loading from JSON

{
  "page_ranges": {
    "skip": [1, 2],
    "content": [3, -3],
    "endnotes": [-2, -1]
  },
  "exclude_regions": {
    "top": 0.05,
    "bottom": 0.05
  },
  "reading_order_strategy": "y_sort",
  "heading_detection": {
    "font_size_threshold": 1.2
  },
  "image_optimization": {
    "enabled": true,
    "jpeg_quality": 85
  }
}

import json
from conversion.models import ConversionConfig

with open("config.json") as f:
    data = json.load(f)
config = ConversionConfig(**data)