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 very 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:

Inheritance diagram of PageJob

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.