Difference: MuPDFWrap (8 vs. 9)

Revision 92021-03-31 - JulianSmith

Line: 1 to 1
 
META TOPICPARENT name="JulianSmith"

C++ and Python APIs for MuPDF

Line: 6 to 6
 

Overview

Changed:
<
<

API Stability

>
>

The C++ MuPDF API

 
Changed:
<
<
The C++ and Python MuPDF APIs are currently an alpha release and liable to change.
>
>
  • Auto-generated from the MuPDF C API.
  • Provides C++ functions that wrap most fz_ and pdf_ functions.
  • Provides C++ classes that wrap most fz_ and pdf_ structs.
  • Class methods provide access to most of the underlying C API functions (except for functions that don't take struct args such as fz_strlcpy()).
  • fz_ exceptions are converted into C++ exceptions.
  • Functions and methods do not take fz_context arguments. (Automatically-generated per-thread contexts are used internally.)
  • Provides a small number of extensions beyond the basic C API:
    • Some generated classes have extra support for iteration.
    • Some custom class methods and constructors.
    • Functions for generating a text representation of some simple 'POD' structs. For example for fz_rect we provide these functions:
              std::ostream& operator<< (std::ostream& out, const fz_rect& rhs);
              std::ostream& operator<< (std::ostream& out, const Rect& rhs);
              std::string to_string_fz_rect(const fz_rect& s);
              std::string to_string(const fz_rect& s);
              std::string Rect::to_string() const;
These each generate text such as: (x0=90.51 y0=160.65 x1=501.39 y1=215.6)
 
Changed:
<
<
  • Changes that apply to both C++ and Python bindings:
    • Improved access to metadata - added Document::lookup_metadata() overload that returns a std::string. Also provided extern const std::vector<std::string> metadata_keys; containing a list of the supported keys.
    • Iterating over Outline=='s now returns ==OutlineIterator objects so that depth information is also available.
    • Fixed a reference-counting bug in iterators.
    • Page::search_page() now returns a std::vector.
    • PdfDocument now has a default constructor which uses pdf_create_document().
    • Include wrappers for functions that return fz_outline*, e.g. Outline Document::load_outline();.
    • Removed potentially slow call of getenv("MUPDF_trace") in every C++ wrapper function.
    • Removed special-case naming of wrappers for fz_run_page() - they are now called mupdf::run_page() and mupdf::Page::run_page(), not mupdf::run() etc.
    • Added text representation of POD structs:
      • In C++ we provide auto-generated operator<< functions and to_string() methods that generate text representations of POD structs and their C++ wrapping classes.
      • In Python these are wrapped into __str__() methods in the equivalent Python classes so POD instances convert into strings using the standard Python mechanisms such as str(), %s and {}.
      • The string representation uses space-separated name=value items within round brackets. For example a fz_rect or a mupdf::Rect will be represented as a string such as: (x0=90.51 y0=160.65 x1=501.39 y1=215.6)
>
>

The Python MuPDF API

 
Changed:
<
<
  • Changes that apply only to Python:
    • Improved handling of out-parameters:
      • If a function or method has out-parameters we now systematically return a Python tuple containing any return value followed by the out-parameters.
      • Don't treat FILE* or pointer-to-const as an out-parameter.
    • Added methods for getting the content of a mupdf.Buffer as a Python bytes instance.
    • Added Python access to nested unions in fz_stext_block wrapper class mupdf.StextBlock.
    • Allow the MuPDF Python bindings to be installed with pip.
      • This uses a source distribution of mupdf that has been uploaded to pypi.org in the normal way.
      • Note that installation involves compiling the C, C++ and Python bindings so will take a few minutes. It requires SWIG to be installed.
      • Pre-build wheels are not currently provided.
>
>
  • A python module called mupdf.
  • Generated from the C++ MuPDF API's header files.
  • Allows implementation of mutool in Python - see mupdf:scripts/mutool.py and mupdf:scripts/mutool_draw.py.
  • Text representation for simple 'POD' structs.
          rect = mupdf.Rect(...)
          print(rect) # Will output text such as: (x0=90.51 y0=160.65 x1=501.39 y1=215.6)
This works for Python class wrappers for classes where the C++ API defines a to_string() method as described above; these Python classes will have a __str__() method.

API Stability

 
Added:
>
>
The C++ and Python MuPDF APIs are currently a beta release and liable to change.
 

Installing the Python mupdf module using pip

Line: 117 to 123
 
    • Include wrappers for functions that return fz_outline*, e.g. Outline Document::load_outline();.
    • Removed potentially slow call of getenv("MUPDF_trace") in every C++ wrapper function.
    • Removed special-case naming of wrappers for fz_run_page() - they are now called mupdf::run_page() and mupdf::Page::run_page(), not mupdf::run() etc.
Changed:
<
<
    • Added text representation of POD structs:
      • In C++ we provide auto-generated operator<< functions and to_string() methods that generate a text representations of POD structs and their C++ wrapping classes.
      • In Python these are wrapped into __str__() methods in the equivalent Python classes so POD instances convert into strings using the standard Python mechanisms such as str(), %s and {}.
      • The string representation uses space-separated name=value items within round brackets. For example a fz_rect or a mupdf::Rect will be represented as a string such as: (x0=90.51 y0=160.65 x1=501.39 y1=215.6)
>
>
    • Added text representation of POD structs.
 
  • Changes that apply only to Python:
    • Improved handling of out-parameters:
Line: 131 to 133
 
    • Added Python access to nested unions in fz_stext_block wrapper class mupdf.StextBlock.
    • Allow the MuPDF Python bindings to be installed with pip.
      • This uses a source distribution of mupdf that has been uploaded to pypi.org in the normal way.
Changed:
<
<
      • Note that installation involves compiling the C, C++ and Python bindings so will take a few minutes. It requires SWIG to be installed.
>
>
      • Installation involves compiling the C, C++ and Python bindings so will take a few minutes. It requires SWIG to be installed.
 
      • Pre-build wheels are not currently provided.
Line: 184 to 186
 
  • platform/c++/include/html/index.html [C++ API]
  • build/shared-release/mupdf.html [Python API]
Changed:
<
<
Note that the content is ultimately all generated from the MuPDF C header file comments.
>
>
The content is ultimately all generated from the MuPDF C header file comments.
 
 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright 2014 Artifex Software Inc