Layout Analyzer Skill

Overview

This skill enables document layout analysis using surya - an advanced document understanding system. Detect text blocks, tables, figures, headings, and determine reading order in complex documents.

How to Use

• Provide the document image or PDF

• Specify what layout elements to detect

• I'll analyze the structure and return detected regions

Example prompts:

• "Analyze the layout of this document page"

• "Detect all tables and text blocks in this image"

• "Determine the reading order for this PDF page"

• "Find headings and paragraphs in this document"

Domain Knowledge

surya Fundamentals

from surya.detection import DetectionPredictor

from surya.layout import LayoutPredictor

from surya.reading_order import ReadingOrderPredictor

from PIL import Image

# Load image

image = Image.open("document.png")

# Detect layout elements

layout_predictor = LayoutPredictor()

layout_result = layout_predictor([image])

Layout Element Types

Element

Description

Text

Regular paragraph text

Title

Document/section titles

Section-header

Section headings

List-item

Bulleted/numbered items

Table

Tabular data

Figure

Images/diagrams

Caption

Figure/table captions

Footnote

Footnotes

Formula

Mathematical equations

Page-header

Headers

Page-footer

Footers

Text Detection

from surya.detection import DetectionPredictor

from PIL import Image

# Initialize detector

detector = DetectionPredictor()

# Load image

image = Image.open("document.png")

# Detect text regions

results = detector([image])

# Access results

for page_result in results:

    for bbox in page_result.bboxes:

        print(f"Text region: {bbox.bbox}")

        print(f"Confidence: {bbox.confidence}")

Layout Analysis

from surya.layout import LayoutPredictor

from PIL import Image

# Initialize layout predictor

layout_predictor = LayoutPredictor()

# Analyze layout

image = Image.open("document.png")

layout_results = layout_predictor([image])

# Process results

for page_result in layout_results:

    for element in page_result.bboxes:

        print(f"Type: {element.label}")

        print(f"Bbox: {element.bbox}")

        print(f"Confidence: {element.confidence}")

Reading Order Detection

from surya.reading_order import ReadingOrderPredictor

from surya.layout import LayoutPredictor

from PIL import Image

# Get layout first

layout_predictor = LayoutPredictor()

image = Image.open("document.png")

layout_results = layout_predictor([image])

# Determine reading order

reading_order_predictor = ReadingOrderPredictor()

order_results = reading_order_predictor([image], layout_results)

# Access ordered elements

for page_result in order_results:

    for i, element in enumerate(page_result.ordered_bboxes):

        print(f"{i+1}. {element.label}: {element.bbox}")

OCR with Layout

from surya.ocr import OCRPredictor

from surya.layout import LayoutPredictor

from PIL import Image

# Initialize predictors

ocr_predictor = OCRPredictor()

layout_predictor = LayoutPredictor()

# Load image

image = Image.open("document.png")

# Get layout

layout_results = layout_predictor([image])

# Run OCR

ocr_results = ocr_predictor([image])

# Combine results

for layout, ocr in zip(layout_results, ocr_results):

    for layout_elem in layout.bboxes:

        print(f"Element: {layout_elem.label}")

        # Find OCR text within this layout element

        for text_line in ocr.text_lines:

            if boxes_overlap(layout_elem.bbox, text_line.bbox):

                print(f"  Text: {text_line.text}")

Processing PDFs

from surya.layout import LayoutPredictor

from pdf2image import convert_from_path

def analyze_pdf_layout(pdf_path):

    """Analyze layout of all pages in PDF."""

    # Convert PDF to images

    images = convert_from_path(pdf_path)

    # Initialize predictor

    layout_predictor = LayoutPredictor()

    # Analyze all pages

    results = layout_predictor(images)

    document_structure = []

    for page_num, page_result in enumerate(results):

        page_elements = []

        for element in page_result.bboxes:

            page_elements.append({

                'type': element.label,

                'bbox': element.bbox,

                'confidence': element.confidence

            })

        document_structure.append({

            'page': page_num + 1,

            'elements': page_elements

        })

    return document_structure

structure = analyze_pdf_layout("document.pdf")

Visualization

from surya.layout import LayoutPredictor

from PIL import Image, ImageDraw, ImageFont

def visualize_layout(image_path, output_path):

    """Visualize detected layout elements."""

    image = Image.open(image_path)

    layout_predictor = LayoutPredictor()

    results = layout_predictor([image])

    # Create drawing context

    draw = ImageDraw.Draw(image)

    # Color mapping for element types

    colors = {

        'Text': 'blue',

        'Title': 'red',

        'Table': 'green',

        'Figure': 'purple',

        'Section-header': 'orange',

        'List-item': 'cyan',

    }

    for element in results[0].bboxes:

        bbox = element.bbox

        color = colors.get(element.label, 'gray')

        # Draw rectangle

        draw.rectangle(bbox, outline=color, width=2)

        # Add label

        draw.text((bbox[0], bbox[1] - 15),

                  f"{element.label} ({element.confidence:.2f})",

                  fill=color)

    image.save(output_path)

    return output_path

Best Practices

• Use High-Quality Images: 150+ DPI for best results

• Preprocess if Needed: Deskew rotated documents

• Validate Results: Check confidence scores

• Handle Multi-page: Process pages individually

• Combine with OCR: Get text within detected regions

Common Patterns

Document Structure Extraction

def extract_document_structure(image_path):

    """Extract hierarchical document structure."""

    from surya.layout import LayoutPredictor

    from surya.reading_order import ReadingOrderPredictor

    image = Image.open(image_path)

    # Get layout

    layout_predictor = LayoutPredictor()

    layout_results = layout_predictor([image])

    # Get reading order

    order_predictor = ReadingOrderPredictor()

    order_results = order_predictor([image], layout_results)

    structure = {

        'title': None,

        'sections': [],

        'tables': [],

        'figures': []

    }

    current_section = None

    for element in order_results[0].ordered_bboxes:

        if element.label == 'Title':

            structure['title'] = element

        elif element.label == 'Section-header':

            current_section = {'header': element, 'content': []}

            structure['sections'].append(current_section)

        elif element.label == 'Table':

            structure['tables'].append(element)

        elif element.label == 'Figure':

            structure['figures'].append(element)

        elif current_section and element.label in ['Text', 'List-item']:

            current_section['content'].append(element)

    return structure

Table Region Extraction

def extract_table_regions(image_path):

    """Extract table regions from document."""

    from surya.layout import LayoutPredictor

    image = Image.open(image_path)

    layout_predictor = LayoutPredictor()

    results = layout_predictor([image])

    tables = []

    for element in results[0].bboxes:

        if element.label == 'Table':

            bbox = element.bbox

            # Crop table region

            table_image = image.crop(bbox)

            tables.append({

                'bbox': bbox,

                'image': table_image,

                'confidence': element.confidence

            })

    return tables

Examples

Example 1: Academic Paper Analysis

from surya.layout import LayoutPredictor

from surya.reading_order import ReadingOrderPredictor

from pdf2image import convert_from_path

def analyze_academic_paper(pdf_path):

    """Analyze structure of academic paper."""

    images = convert_from_path(pdf_path)

    layout_predictor = LayoutPredictor()

    order_predictor = ReadingOrderPredictor()

    paper_structure = {

        'pages': [],

        'element_counts': {

            'Title': 0,

            'Section-header': 0,

            'Text': 0,

            'Table': 0,

            'Figure': 0,

            'Formula': 0,

            'Footnote': 0

        }

    }

    layout_results = layout_predictor(images)

    order_results = order_predictor(images, layout_results)

    for page_num, (layout, order) in enumerate(zip(layout_results, order_results)):

        page_structure = {

            'page': page_num + 1,

            'elements': []

        }

        for element in order.ordered_bboxes:

            page_structure['elements'].append({

                'type': element.label,

                'bbox': element.bbox,

                'order': element.position

            })

            # Count element types

            if element.label in paper_structure['element_counts']:

                paper_structure['element_counts'][element.label] += 1

        paper_structure['pages'].append(page_structure)

    return paper_structure

paper = analyze_academic_paper('research_paper.pdf')

print(f"Total tables: {paper['element_counts']['Table']}")

print(f"Total figures: {paper['element_counts']['Figure']}")

Example 2: Form Field Detection

from surya.layout import LayoutPredictor

from PIL import Image

def detect_form_fields(image_path):

    """Detect form fields and labels."""

    image = Image.open(image_path)

    layout_predictor = LayoutPredictor()

    results = layout_predictor([image])

    form_fields = []

    for element in results[0].bboxes:

        # Look for text elements that might be labels

        if element.label == 'Text':

            # Check if there's a box/line nearby (potential input field)

            form_fields.append({

                'type': 'potential_label',

                'bbox': element.bbox,

                'confidence': element.confidence

            })

    return form_fields

fields = detect_form_fields('form.png')

print(f"Found {len(fields)} potential form elements")

Example 3: Multi-column Article

from surya.layout import LayoutPredictor

from surya.reading_order import ReadingOrderPredictor

from PIL import Image

def process_multicolumn_article(image_path):

    """Process multi-column article layout."""

    image = Image.open(image_path)

    layout_predictor = LayoutPredictor()

    order_predictor = ReadingOrderPredictor()

    layout_results = layout_predictor([image])

    order_results = order_predictor([image], layout_results)

    # Group elements by column

    image_width = image.width

    column_threshold = image_width / 2

    columns = {

        'left': [],

        'right': [],

        'full_width': []

    }

    for element in order_results[0].ordered_bboxes:

        bbox = element.bbox

        element_center = (bbox[0] + bbox[2]) / 2

        element_width = bbox[2] - bbox[0]

        # Determine column

        if element_width > column_threshold * 1.5:

            columns['full_width'].append(element)

        elif element_center < column_threshold:

            columns['left'].append(element)

        else:

            columns['right'].append(element)

    return {

        'layout': 'multi-column',

        'columns': columns,

        'reading_order': order_results[0].ordered_bboxes

    }

article = process_multicolumn_article('newspaper_page.png')

print(f"Left column: {len(article['columns']['left'])} elements")

print(f"Right column: {len(article['columns']['right'])} elements")

Limitations

• Handwritten layouts may be inaccurate

• Very small text regions may be missed

• Complex nested layouts challenging

• GPU recommended for batch processing

• Multi-language support varies

Installation

pip install surya-ocr

# For PDF processing

pip install pdf2image

Resources

• surya GitHub

• Model Documentation

• Examples