Document pages¶

class djvu.decode.DocumentPages¶

Pages of a document.

Use Document.pages to obtain instances of this class.

Page indexing is zero-based, i.e. pages[0] stands for the first page.

len(pages) might return 1 when called before receiving a DocInfoMessage.

class djvu.decode.Page¶

Page of a document.

Use Document.pages[N] to obtain instances of this class.

document¶

Return type: Document

file¶

Returns: a file associated with the page.
Return type: File.

n¶

Returns: the page number.

Page indexing is zero-based, i.e. 0 stands for the very first page.

thumbnail¶

Returns: a thumbnail for the page.
Return type: Thumbnail.

get_info([wait=1])¶

Attempt to obtain information about the page without decoding the page.

If wait is true, wait until the information is available.

If the information is not available, raise NotAvailable exception. Then, start fetching the page data, which causes emission of PageInfoMessage messages with empty page_job.

Raises

NotAvailable – see above.
JobFailed – on failure.

width¶

Returns

the page width, in pixels.

Raises

NotAvailable – see get_info().
JobFailed – on failure.

height¶

Returns

the page height, in pixels.

Raises

NotAvailable – see get_info().
JobFailed – on failure.

size¶

Returns

(page.width, page.height)

Raises

NotAvailable – see get_info().
JobFailed – on failure.

dpi¶

Returns

the page resolution, in pixels per inch.

Raises

NotAvailable – see get_info().
JobFailed – on failure.

rotation¶

Returns

the initial page rotation, in degrees.

Raises

NotAvailable – see get_info().
JobFailed – on failure.

version¶

Returns

the page version.

Raises

NotAvailable – see get_info().
JobFailed – on failure.

dump¶

Returns: a text describing the contents of the page using the same format as the djvudump command.

If the information is not available, raise NotAvailable exception. Then PageInfoMessage messages with empty page_job may be emitted.

Raises: NotAvailable – see above.

decode([wait=1])¶

Initiate data transfer and decoding threads for the page.

If wait is true, wait until the job is done.

Return type

PageJob.

Raises

NotAvailable – if called before receiving the DocInfoMessage.
JobFailed – if document decoding failed.

annotations¶

Return type: PageAnnotations

text¶

Return type: PageText

class djvu.decode.PageJob¶

Inheritance diagram:

A page decoding job.

Use Page.decode() to obtain instances of this class.

width¶

Returns: the page width in pixels.
Raises: NotAvailable – before receiving a PageInfoMessage.

height¶

Returns: the page height in pixels.
Raises: NotAvailable – before receiving a PageInfoMessage.

size¶

Returns: (page_job.width, page_job.height)
Raises: NotAvailable – before receiving a PageInfoMessage.

dpi¶

Returns: the page resolution in pixels per inch.
Raises: NotAvailable – before receiving a PageInfoMessage.

gamma¶

Returns: the gamma of the display for which this page was designed.
Raises: NotAvailable – before receiving a PageInfoMessage.

version¶

Returns: the version of the DjVu file format.
Raises: NotAvailable – before receiving a PageInfoMessage.

type¶

Returns: the type of the page data.

Possible values are:

PAGE_TYPE_UNKNOWN¶

PAGE_TYPE_BITONAL¶

PAGE_TYPE_PHOTO¶

PAGE_TYPE_COMPOUND¶

Raises: NotAvailable – before receiving a PageInfoMessage.

initial_rotation¶

Returns: the counter-clockwise page rotation angle (in degrees) specified by the orientation flags in the DjVu file.

Warning

This is useful because maparea coordinates in the annotation chunks are expressed relative to the rotated coordinates whereas text coordinates in the hidden text data are expressed relative to the unrotated coordinates.

rotation¶

Returns: the counter-clockwise rotation angle (in degrees) for the page.

The rotation is automatically taken into account by render() method and width and height properties.

render(self, mode, page_rect, render_rect, pixel_format[, row_alignment=1][, buffer=None])¶

Render a segment of a page with arbitrary scale. mode indicates which image layers should be rendered:

Conceptually this method renders the full page into a rectangle page_rect and copies the pixels specified by rectangle render_rect into a buffer. The actual code is much more efficient than that.

pixel_format (a PixelFormat instance) specifies the expected pixel format. Each row will start at row_alignment bytes boundary.

Data will be saved to the provided buffer or to a newly created string.

This method makes a best effort to compute an image that reflects the most recently decoded data.

Raises: NotAvailable – to indicate that no image could be computed at this point.

class djvu.decode.Thumbnail¶

Thumbnail for a page.

Use Page.thumbnail to obtain instances of this class.

page¶

Returns: the page.

status¶

Determine whether the thumbnail is available.

Returns: a JobException subclass indicating the current job status.

calculate()¶

Determine whether the thumbnail is available. If it’s not, initiate the thumbnail calculating job. Regardless of its success, the completion of the job is signalled by a subsequent ThumbnailMessage.

Return a JobException subclass indicating the current job status.

render((w0, h0)[, pixel_format][, row_alignment=1][, dry_run=False][, buffer=None])¶

Render the thumbnail:

not larger than w0 × h0 pixels;
using the pixel_format (a PixelFormat instance) pixel format;
with each row starting at row_alignment bytes boundary;
into the provided buffer or to a newly created string.

Returns: a ((w1, h1, row_size), data) tuple.

w1 and h1 are actual thumbnail dimensions in pixels (w1 ≤ w0 and h1 ≤ h0);
row_size is length of each image row, in bytes;
data is None if dry_run is true; otherwise is contains the actual image data.

Raises: NotAvailable – when no thumbnail is available.