structured-text.h

Go to the documentation of this file.

// Copyright (C) 2004-2026 Artifex Software, Inc.
//
// This file is part of MuPDF.
//
// MuPDF is free software: you can redistribute it and/or modify it under the
// terms of the GNU Affero General Public License as published by the Free
// Software Foundation, either version 3 of the License, or (at your option)
// any later version.
//
// MuPDF is distributed in the hope that it will be useful, but WITHOUT ANY
// WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
// FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
// details.
//
// You should have received a copy of the GNU Affero General Public License
// along with MuPDF. If not, see <https://www.gnu.org/licenses/agpl-3.0.en.html>
//
// Alternative licensing terms are available from the licensor.
// For commercial licensing, see <https://www.artifex.com/> or contact
// Artifex Software, Inc., 39 Mesa Street, Suite 108A, San Francisco,
// CA 94129, USA, for further information.
 
#ifndef MUPDF_FITZ_STRUCTURED_TEXT_H
#define MUPDF_FITZ_STRUCTURED_TEXT_H
 
#include "mupdf/fitz/system.h"
#include "mupdf/fitz/types.h"
#include "mupdf/fitz/context.h"
#include "mupdf/fitz/geometry.h"
#include "mupdf/fitz/font.h"
#include "mupdf/fitz/image.h"
#include "mupdf/fitz/output.h"
#include "mupdf/fitz/device.h"
#include "mupdf/fitz/pool.h"

typedef struct fz_layout_char
{
    float x, advance;
    const char *p; /* location in source text of character */
    struct fz_layout_char *next;
} fz_layout_char;
 
typedef struct fz_layout_line
{
    float x, y, font_size;
    const char *p; /* location in source text of start of line */
    fz_layout_char *text;
    struct fz_layout_line *next;
} fz_layout_line;
 
typedef struct
{
    fz_pool *pool;
    fz_matrix matrix;
    fz_matrix inv_matrix;
    fz_layout_line *head, **tailp;
    fz_layout_char **text_tailp;
} fz_layout_block;

fz_layout_block *fz_new_layout(fz_context *ctx);

void fz_drop_layout(fz_context *ctx, fz_layout_block *block);

void fz_add_layout_line(fz_context *ctx, fz_layout_block *block, float x, float y, float h, const char *p);

void fz_add_layout_char(fz_context *ctx, fz_layout_block *block, float x, float w, const char *p);

 
typedef struct fz_stext_char fz_stext_char;
typedef struct fz_stext_line fz_stext_line;
typedef struct fz_stext_block fz_stext_block;
typedef struct fz_stext_struct fz_stext_struct;
typedef struct fz_stext_grid_positions fz_stext_grid_positions;

enum
{
    FZ_STEXT_PRESERVE_LIGATURES = 1,
    FZ_STEXT_PRESERVE_WHITESPACE = 2,
    FZ_STEXT_PRESERVE_IMAGES = 4,
    FZ_STEXT_INHIBIT_SPACES = 8,
    FZ_STEXT_DEHYPHENATE = 16,
    FZ_STEXT_PRESERVE_SPANS = 32,
    FZ_STEXT_CLIP = 64,
    FZ_STEXT_USE_CID_FOR_UNKNOWN_UNICODE = 128,
    FZ_STEXT_COLLECT_STRUCTURE = 256,
    FZ_STEXT_ACCURATE_BBOXES = 512,
    FZ_STEXT_COLLECT_VECTORS = 1024,
    FZ_STEXT_IGNORE_ACTUALTEXT = 2048,
    FZ_STEXT_SEGMENT = 4096,
    FZ_STEXT_PARAGRAPH_BREAK = 8192,
    FZ_STEXT_TABLE_HUNT = 16384,
    FZ_STEXT_COLLECT_STYLES = 32768,
    FZ_STEXT_USE_GID_FOR_UNKNOWN_UNICODE = 65536,
    FZ_STEXT_CLIP_RECT = (1<<17),
    FZ_STEXT_ACCURATE_ASCENDERS = (1<<18),
    FZ_STEXT_ACCURATE_SIDE_BEARINGS = (1<<19),
    FZ_STEXT_LAZY_VECTORS = (1<<20),
    FZ_STEXT_FUZZY_VECTORS = (1<<21),
 
    /* An old, deprecated option. */
    FZ_STEXT_MEDIABOX_CLIP = FZ_STEXT_CLIP
};

 
typedef struct
{
    fz_rect mediabox;
    int chapter;
    int page;
} fz_stext_page_details;

typedef struct
{
    int refs;
    fz_pool *pool;
    fz_rect mediabox;
    fz_stext_block *first_block;
 
    /* The following fields are only of use to the routines that
     * build an fz_stext_page. They change during page construction
     * and their meaning is subject to change. These values should
     * not be used by anything outside of the stext device. */
    fz_stext_block *last_block;
    fz_stext_struct *last_struct;
 
    /* An array of fz_stext_page_details */
    fz_pool_array *id_list;
} fz_stext_page;

fz_stext_page *fz_keep_stext_page(fz_context *ctx, fz_stext_page *page);

fz_stext_page_details *fz_stext_page_details_for_block(fz_context *ctx, fz_stext_page *page, fz_stext_block *block);
 
enum
{
    FZ_STEXT_BLOCK_TEXT = 0,
    FZ_STEXT_BLOCK_IMAGE = 1,
    FZ_STEXT_BLOCK_STRUCT = 2,
    FZ_STEXT_BLOCK_VECTOR = 3,
    FZ_STEXT_BLOCK_GRID = 4
};
 
enum
{
    FZ_STEXT_TEXT_JUSTIFY_UNKNOWN = 0,
    FZ_STEXT_TEXT_JUSTIFY_LEFT = 1,
    FZ_STEXT_TEXT_JUSTIFY_CENTER = 2,
    FZ_STEXT_TEXT_JUSTIFY_RIGHT = 3,
    FZ_STEXT_TEXT_JUSTIFY_FULL = 4,
};
 
enum
{
    /* Indicates that this vector came from a stroked
     * path. */
    FZ_STEXT_VECTOR_IS_STROKED = 1,
 
    /* Indicates that this vector came from a rectangular
     * (axis-aligned) path (or path segment). */
    FZ_STEXT_VECTOR_IS_RECTANGLE = 2,
 
    /* Indicates that this vector came from a path
     * segment, and more segments from this same path are
     * still to come. */
    FZ_STEXT_VECTOR_CONTINUES = 4,
 
    /* Indicates that this was detected as being
     * part of an underline/strikeout/highlight. */
    FZ_STEXT_VECTOR_IS_HIGHLIGHT = 8,
    FZ_STEXT_VECTOR_IS_UNDERLINE = 16,
    FZ_STEXT_VECTOR_IS_STRIKEOUT = 32
};
 
enum
{
    /* Indicates that cell contents cross the right hand edge. */
    FZ_STEXT_GRID_H_CROSSED = 1,
    /* Indicates that cell contents cross the bottom edge. */
    FZ_STEXT_GRID_V_CROSSED = 2,
    /* Indicates that the cell has a border on the left hand edge. */
    FZ_STEXT_GRID_L_BORDER = 4,
    /* Indicates that the cell has a border on the top edge. */
    FZ_STEXT_GRID_T_BORDER = 8,
    /* Indicates that the cell has content (which may be a space!) */
    FZ_STEXT_GRID_FULL = 16,
};
 
/* This structure is experimental, and subject to change. */
typedef struct
{
    /* A 2x2 table, will be represented as a 3x3 set of
     * cells. The rightmost column and bottommost row
     * exist just to give information about borders on
     * the edges. For such a table w=h=3.
     */
    int w;
    int h;
    /* Followed by w*h entries. */
    struct {
        unsigned int flags;
    } info[FZ_FLEXIBLE_ARRAY];
} fz_stext_grid_info;

struct fz_stext_block
{
    int type;
    int id;
    fz_rect bbox;
    union {
        struct { fz_stext_line *first_line, *last_line; int flags;} t;
        struct { fz_matrix transform; fz_image *image; } i;
        struct { fz_stext_struct *down; int index; } s;
        struct { uint32_t flags; uint32_t argb; } v;
        struct { fz_stext_grid_positions *xs; fz_stext_grid_positions *ys; fz_stext_grid_info *info; } b;
    } u;
    fz_stext_block *prev, *next;
};
 
typedef enum
{
    FZ_STEXT_LINE_FLAGS_JOINED = 1
} fz_stext_line_flags;

struct fz_stext_line
{
    uint8_t wmode; /* 0 for horizontal, 1 for vertical */
    uint8_t flags;
    fz_point dir; /* normalized direction of baseline */
    fz_rect bbox;
    fz_stext_char *first_char, *last_char;
    fz_stext_line *prev, *next;
};

struct fz_stext_char
{
    int c; /* unicode character value */
    uint16_t bidi; /* even for LTR, odd for RTL - probably only needs 8 bits? */
    uint16_t flags;
    uint32_t argb; /* sRGB hex color (alpha in top 8 bits, then r, then g, then b in low bits) */
    fz_point origin;
    fz_quad quad;
    float size;
    fz_font *font;
    fz_stext_char *next;
};
 
enum
{
    FZ_STEXT_STRIKEOUT = 1,
    FZ_STEXT_UNDERLINE = 2,
    FZ_STEXT_SYNTHETIC = 4,
    FZ_STEXT_BOLD = 8, /* Either real or 'fake' bold */
    FZ_STEXT_FILLED = 16,
    FZ_STEXT_STROKED = 32,
    FZ_STEXT_CLIPPED = 64,
    FZ_STEXT_UNICODE_IS_CID = 128,
    FZ_STEXT_UNICODE_IS_GID = 256,
    FZ_STEXT_SYNTHETIC_LARGE = 512,
    FZ_STEXT_HIGHLIGHT = 1024
};

struct fz_stext_struct
{
    /* up points to the block that contains this fz_stext_struct. */
    fz_stext_block *up;
    /* parent points to the struct that has up as one of its children.
     * parent is useful for doing depth first traversal without having
     * to store the entire chain of structs in the iterator. */
    fz_stext_struct *parent;
 
    /* first_block points to the first child of this node (or NULL
     * if there are none). */
    fz_stext_block *first_block;
    /* last_block points to the last child of this node (or NULL
     * if there are none). */
    fz_stext_block *last_block;
 
    /* We have a set of 'standard' structure types. Every structure
     * element should correspond to one of these. */
    fz_structure standard;
    /* Documents can use their own non-standard structure types, which
     * are held as 'raw' strings. */
    char raw[FZ_FLEXIBLE_ARRAY];
};
 
/* An example to show how fz_stext_blocks and fz_stext_structs interact:
 *
 *         [fz_stext_page]
 *             |
 *  first_block|
 *             |
 *            \|/
 *  [fz_stext_block:TEXT]<->[fz_stext_block:STRUCT]<->[fz_stext_block:IMG]
 *                           u.s.down|   /|\
 *                                   |    |
 *                                  \|/   |up
 *                             [fz_stext_struct]<---------.
 *                                |       |               |
 *                     first_block|       |last_block     |
 *         _______________________|       |               |
 *        |                               |               |
 *        |                               |               |
 *       \|/                             \|/              |
 *  [fz_stext_block:...]<->...<->[fz_stext_block:STRUCT]  |
 *                                  |  /|\                |
 *                          u.s.down|   |up               |
 *                                 \|/  |           parent|
 *                               [fz_stext_struct]--------'
 *                                  |   |
 *                       first_block|   |last_block
 *                                  :   :
 */
 
 typedef struct
 {
    int reinforcement;
    float pos;
    float min;
    float max;
    int uncertainty;
 } fz_stext_grid_divider;
 
 struct fz_stext_grid_positions
 {
    int len;
    int max_uncertainty;
    fz_stext_grid_divider list[FZ_FLEXIBLE_ARRAY];
 };
 
FZ_DATA extern const char *fz_stext_options_usage;

fz_stext_page *fz_new_stext_page(fz_context *ctx, fz_rect mediabox);
void fz_drop_stext_page(fz_context *ctx, fz_stext_page *page);

void fz_print_stext_page_as_html(fz_context *ctx, fz_output *out, fz_stext_page *page, int id);
void fz_print_stext_header_as_html(fz_context *ctx, fz_output *out);
void fz_print_stext_trailer_as_html(fz_context *ctx, fz_output *out);

void fz_print_stext_page_as_xhtml(fz_context *ctx, fz_output *out, fz_stext_page *page, int id);
void fz_print_stext_header_as_xhtml(fz_context *ctx, fz_output *out);
void fz_print_stext_trailer_as_xhtml(fz_context *ctx, fz_output *out);

void fz_print_stext_page_as_xml(fz_context *ctx, fz_output *out, fz_stext_page *page, int id);

typedef enum {
    FZ_STEXT_XML_FLAGS_CHARS = 1,
    FZ_STEXT_XML_FLAGS_POINTERS = 2
} fz_stext_xml_flags;
void fz_print_stext_page_as_xml_with_flags(fz_context *ctx, fz_output *out, fz_stext_page *page, int id, fz_stext_xml_flags flags);

void fz_debug_stext_page(fz_context *ctx, fz_stext_page *page, int id);
 

void fz_print_stext_page_as_json(fz_context *ctx, fz_output *out, fz_stext_page *page, float scale);

void fz_print_stext_page_as_text(fz_context *ctx, fz_output *out, fz_stext_page *page);

int fz_search_stext_page(fz_context *ctx, fz_stext_page *text, const char *needle, int *hit_mark, fz_quad *hit_bbox, int hit_max);

typedef int (fz_search_callback_fn)(fz_context *ctx, void *opaque, int num_quads, fz_quad *hit_bbox);

typedef int (fz_match_callback_fn)(fz_context *ctx, void *opaque, int num_quads, fz_quad *hit_bbox, int chapter, int page);

int fz_search_stext_page_cb(fz_context *ctx, fz_stext_page *text, const char *needle, fz_search_callback_fn *cb, void *opaque);

int fz_highlight_selection(fz_context *ctx, fz_stext_page *page, fz_point a, fz_point b, fz_quad *quads, int max_quads);
 
enum
{
    FZ_SELECT_CHARS,
    FZ_SELECT_WORDS,
    FZ_SELECT_LINES,
};
 
fz_quad fz_snap_selection(fz_context *ctx, fz_stext_page *page, fz_point *ap, fz_point *bp, int mode);

char *fz_copy_selection(fz_context *ctx, fz_stext_page *page, fz_point a, fz_point b, int crlf);

char *fz_copy_rectangle(fz_context *ctx, fz_stext_page *page, fz_rect area, int crlf);

typedef struct
{
    int vertically_collapse_bordered_cells;
} fz_table_hunt_options;
 
enum {
    /* Never collapse the contents of bordered cells vertically. */
    FZ_TABLE_HUNT_VERTICAL_COLLAPSE_NO = 0,
 
    /* Always collapse the contents of bordered cells vertically. */
    FZ_TABLE_HUNT_VERTICAL_COLLAPSE_YES = 1
};
 
void fz_init_table_hunt_options(fz_context *ctx, fz_table_hunt_options *opts);

fz_table_hunt_options *fz_parse_table_hunt_options(fz_context *ctx, fz_table_hunt_options *opts, const char *args);

void fz_apply_table_hunt_options(fz_context *ctx, fz_table_hunt_options *opts, fz_options *options);
 

typedef struct
{
    int flags;
    float scale;
    fz_rect clip;
    fz_table_hunt_options table_hunt_options;
} fz_stext_options;
 
void fz_init_stext_options(fz_context *ctx, fz_stext_options *opts);

fz_stext_options *fz_parse_stext_options(fz_context *ctx, fz_stext_options *opts, const char *string);

void fz_apply_stext_options(fz_context *ctx, fz_stext_options *opts, fz_options *options);

int fz_segment_stext_page(fz_context *ctx, fz_stext_page *page);

int fz_segment_stext_rect(fz_context *ctx, fz_stext_page *page, fz_rect rect);

void fz_paragraph_break(fz_context *ctx, fz_stext_page *page);

void fz_table_hunt(fz_context *ctx, fz_stext_page *page, const fz_table_hunt_options *opts);

void fz_table_hunt_within_bounds(fz_context *ctx, fz_stext_page *page, fz_rect bounds, const fz_table_hunt_options *opts);

fz_stext_block *
fz_find_table_within_bounds(fz_context *ctx, fz_stext_page *page, fz_rect bounds, const fz_table_hunt_options *opts);

fz_stext_block *
fz_find_table_within_grid(fz_context *ctx, fz_stext_page *page, fz_stext_grid_positions *xpos, fz_stext_grid_positions *ypos, float limit, const fz_table_hunt_options *opts);

int
fz_propose_table_within_bounds(fz_context *ctx, fz_stext_page *page, fz_rect bounds, fz_stext_grid_positions **xposp, fz_stext_grid_positions **yposp, const fz_table_hunt_options *opts);
 

fz_device *fz_new_stext_device(fz_context *ctx, fz_stext_page *page, const fz_stext_options *options);

fz_device *
fz_new_stext_device_for_page(fz_context *ctx, fz_stext_page *stext_page, const fz_stext_options *opts, int chapter_num, int page_num, fz_rect mediabox);
 

fz_device *fz_new_ocr_device(fz_context *ctx, fz_device *target, fz_matrix ctm, fz_rect mediabox, int with_list, const char *language,
            const char *datadir, int (*progress)(fz_context *, void *, int), void *progress_arg);
 
fz_device *fz_new_ocr_device_with_options(fz_context *ctx, fz_device *target, fz_matrix ctm, fz_rect mediabox, int with_list, const char *language,
            const char *datadir, int (*progress)(fz_context *, void *, int), void *progress_arg, fz_options *options);
 
fz_document *fz_open_reflowed_document(fz_context *ctx, fz_document *underdoc, const fz_stext_options *opts);

int fz_is_unicode_space_equivalent(int c);

int fz_is_unicode_whitespace(int c);

int fz_is_unicode_hyphen(int c);
 
typedef struct fz_search fz_search;
 
typedef enum
{
    FZ_SEARCH_EXACT = 0,
    FZ_SEARCH_IGNORE_CASE = 1,
    FZ_SEARCH_IGNORE_DIACRITICS = 2,
    FZ_SEARCH_REGEXP = 4,
    FZ_SEARCH_KEEP_LINES = 8,
    FZ_SEARCH_KEEP_PARAGRAPHS = 16,
    FZ_SEARCH_KEEP_HYPHENS = 32
} fz_search_options;
 
FZ_DATA extern const char *fz_search_options_usage;
 
void fz_init_search_options(fz_context *ctx, fz_search_options *options);
 
fz_search_options *fz_parse_search_options(fz_context *ctx, fz_search_options *options, const char *args);
 
void fz_apply_search_options(fz_context *ctx, fz_search_options *options, fz_options *opts);

fz_search *fz_new_search(fz_context *ctx, const char *needle, fz_search_options options);
 
typedef enum
{
    /* Ran out of stext to search. Please feed me some more. */
    FZ_SEARCH_MORE_INPUT = 0,
 
    /* We have a match. match structure has been populated. */
    FZ_SEARCH_MATCH = 1,
 
    /* Search complete */
    FZ_SEARCH_COMPLETE
} fz_search_reason;
 
typedef struct
{
    int seq;
    fz_quad quad;
} fz_search_quad;
 
typedef struct
{
    fz_stext_page *page;
    fz_stext_struct *parent;
    fz_stext_block *block;
    fz_stext_line *line;
    fz_stext_char *ch;
} fz_stext_position;
 
typedef struct
{
    int num_quads;
    fz_search_quad *quads;
    fz_stext_position begin, end;
    int begin_seq, end_seq;
} fz_search_match;

typedef struct
{
    fz_search_reason reason;
    union
    {
        int seq_needed;
        fz_search_match *match;
    } u;
} fz_search_result;

fz_search_result fz_search_forwards(fz_context *ctx, fz_search *search);

fz_search_result fz_search_backwards(fz_context *ctx, fz_search *search);

void fz_feed_search(fz_context *ctx, fz_search *search, fz_stext_page *page, int seq);

void fz_drop_search(fz_context *ctx, fz_search *search);

int fz_match_stext_page(fz_context *ctx, fz_stext_page *text, const char *needle, int *hit_mark, fz_quad *hit_bbox, int hit_max, fz_search_options options);

int fz_match_stext_page_cb(fz_context *ctx, fz_stext_page *page, const char *needle, fz_match_callback_fn *cb, void *opaque, fz_search_options options);
 
/*
    Allocator function to make a new STRUCT stext block to be used in
    a given page (and it's 'down' structure, initially empty). Not
    linked in to the overall page structure yet.
*/
fz_stext_block *fz_new_stext_struct(fz_context *ctx, fz_stext_page *page, fz_structure standard, const char *raw, int index);
 
/* Iterators for walking over stext pages */
 
/*
    Iterator definition. The parts of this are subject to change.
*/
typedef struct
{
    fz_stext_page *page;
    fz_stext_struct *parent;
    fz_stext_block *block;
    fz_stext_struct *top;
} fz_stext_page_block_iterator;
 
/*
    Create a new iterator, initialised to point at the first block on the page.
*/
fz_stext_page_block_iterator fz_stext_page_block_iterator_begin(fz_stext_page *page);
 
/*
    Create a new iterator, initialised to point at the given point on the page.
*/
fz_stext_page_block_iterator fz_stext_page_block_iterator_begin_from(fz_stext_page *page, fz_stext_block *block, fz_stext_struct *top);
 
/*
    Create a new iterator, initialised to point at the first non-struct block on the page
    in depth first search order.
*/
fz_stext_page_block_iterator fz_stext_page_block_iterator_begin_dfs(fz_stext_page *page);
 
/*
    Create a new iterator, initialised to point at the first non-struct block on the page
    in depth first search order after the given point. The start point is recorded so that
    the DFS search will 'eod' at the end of the level that block is in.
*/
fz_stext_page_block_iterator fz_stext_page_block_iterator_begin_from_dfs(fz_stext_page *page, fz_stext_block *block, fz_stext_struct *top);
 
/*
    Create a new iterator, initialised to point at the first non-struct block on the page
    in reverse depth first search order.
*/
fz_stext_page_block_iterator fz_stext_page_block_iterator_begin_rdfs(fz_stext_page *page);
 
/*
    Create a new iterator, initialised to point at the first non-struct block on the page
    in reverse depth first search order after the given point. The start point is recorded so that
    the DFS search will 'eod' at the start of the level that block is in.
*/
fz_stext_page_block_iterator fz_stext_page_block_iterator_begin_from_rdfs(fz_stext_page *page, fz_stext_block *block, fz_stext_struct *top);
 
/*
    Move to the next block (never moving upwards).
 
    If there is no next block, iterator.block is returned as NULL.
*/
fz_stext_page_block_iterator fz_stext_page_block_iterator_next(fz_stext_page_block_iterator pos);
 
/*
    On a structure block, this moves the iterator down to the first child of
    that block.
 
    On any other block, this does nothing.
*/
fz_stext_page_block_iterator fz_stext_page_block_iterator_down(fz_stext_page_block_iterator pos);
 
/*
    Move up to the parent of the current block.
 
    If there is no parent, iterator.block is return as NULL.
*/
fz_stext_page_block_iterator fz_stext_page_block_iterator_up(fz_stext_page_block_iterator pos);
 
/*
    Move to the next block (in a depth first traversal style).
 
    The iterator never stops on struct blocks, and instead steps into them.
    At the end of a set of child blocks, it will move back to the parent and
    continue from there. It will never move past the parent given to begin_from,
    if used.
*/
fz_stext_page_block_iterator fz_stext_page_block_iterator_next_dfs(fz_stext_page_block_iterator pos);
 
/*
    Move to the next block (in a reverse depth first traversal style).
 
    The iterator never stops on struct blocks, and instead steps into them.
    At the end of a set of child blocks, it will move back to the parent and
    continue from there. It will never most past the parent given to begin_from,
    if used.
*/
fz_stext_page_block_iterator fz_stext_page_block_iterator_next_rdfs(fz_stext_page_block_iterator pos);
 
/*
    Return true if the iterator is at the end of a list of blocks.
    (No attempt is made to account for whether there is more data after a
    parent block).
*/
int fz_stext_page_block_iterator_eod(fz_stext_page_block_iterator pos);
 
/*
    Return true if the iterator is at the end of a depth first traversal
    of the stext page. The depth first traversal endpoint will be the
    end of the page, or (if begin_from was used) the end of the level
    given at init time.
*/
int fz_stext_page_block_iterator_eod_dfs(fz_stext_page_block_iterator pos);
 
/*
    Return true if the iterator is at the end of a reverse depth first
    traversal of the stext page. The reverse depth first traversal endpoint
    will be the start of the page, or (if begin_from was used) the start
    of the level given at init time.
*/
int fz_stext_page_block_iterator_eod_rdfs(fz_stext_page_block_iterator pos);
 
/*
    Update a given stext page so that the contents within it that fall
    within the given rectangle are contained within a structure tag of the
    given classification.
 
    The code tries not to change the ordering of content as seen from
    a depth first traversal as it does this.
 
    This is an experimental interface. It may be updated or removed in
    future with no warning!
*/
void
fz_classify_stext_rect(fz_context *ctx, fz_stext_page *page, fz_structure classification, fz_rect rect);
 
/*
    Remove any prefix of large white rectangular vectors that (almost)
    fills the page from the stext.
 
    This is an experimental interface. It may be updated or removed in
    future with no warning!
*/
int
fz_stext_remove_page_fill(fz_context *ctx, fz_stext_page *page);
 
typedef struct
{
    /* The maximum width or height that should be considered for rafting. */
    int max_size;
    /* If non-zero, make a combined image, rather than just the bbox. */
    int combine_image;
} fz_image_raft_options;
 
void
fz_stext_raft_images(fz_context *ctx, fz_stext_page *stext, fz_image_raft_options *options);
 
/*
    Flotilla/Raft handling
 
    We call any 2-dimensional area that's covered by (some type of) content
    a raft. i.e. it's made up of several distinct objects ("planks") lashed
    together into something that covers a large flat area (a "raft").
 
    The set of all such non-overlapping rafts on a page can be called a
    "flotilla".
 
    For instance, the borders and/or backgrounds from a table would form a
    raft behind the text content. And the boundaries of that raft might
    help us distinguish that table from an adjacent table on a different
    raft.
 
    While we could theoretically make rafts from anything, images and
    vectors seem like the best bet. We could make rafts from mixed images
    and vectors, but to start with, I think we'll get best results from
    images and vectors separately.
*/
typedef struct fz_flotilla fz_flotilla;
 
/*
    Construct a flotilla from all the (rectangular) vectors on a page.
*/
fz_flotilla *
fz_new_flotilla_from_stext_page_vectors(fz_context *ctx, fz_stext_page *page);
 
/*
    Drop the flotilla.
*/
void
fz_drop_flotilla(fz_context *ctx, fz_flotilla *f);
 
/*
    How many rafts in this flotilla?
*/
int
fz_flotilla_size(fz_context *ctx, fz_flotilla *flot);
 
/*
    Return the bounds of the ith raft in the flotilla.
*/
fz_rect
fz_flotilla_raft_area(fz_context *ctx, fz_flotilla *flot, int i);
 
/*
    Internal debugging function to verify the soundness
    of an stext page.
 
    title: optional string to be printed.
*/
void fz_verify_stext_page(fz_context *ctx, fz_stext_page *page, const char *title);
 
#endif