Difference: MuPDFWrap (1 vs. 6)

Revision 62021-03-01 - JulianSmith

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

C++ and Python APIs for MuPDF

Line: 95 to 95
 
  • scripts/mutool.py
  • scripts/mutool_draw.py
Added:
>
>
Here is some example code that shows all available information about document's Stext blocks, lines and characters:

#!/usr/bin/env python3

import mupdf

def show_stext(document):
    '''
    Shows all available information about Stext blocks, lines and characters.
    '''
    for p in range(document.count_pages()):
        page = document.load_page(p)
        stextpage = mupdf.StextPage(page, mupdf.StextOptions())
        for block in stextpage:
            block_ = block.m_internal
            print(f'block: type={block_.type} bbox=({block_.bbox.x0:6.2f} {block_.bbox.y0:6.2f} {block_.bbox.x1:6.2f} {block_.bbox.y1:6.2f})')
            for line in block:
                line_ = line.m_internal
                print(f'    line: wmode={line_.wmode}'
                        + f' dir=({line_.dir.x} {line_.dir.y})'
                        + f' bbox=({line_.bbox.x0:6.2f} {line_.bbox.y0:6.2f} {line_.bbox.x1:6.2f} {line_.bbox.y1:6.2f})'
                        )
                for char in line:
                    char_ = char.m_internal
                    print(f'        char: {chr(char_.c)!r} c={char_.c:4} color={char_.color}'
                            + f' origin=({char_.origin.x:6.2f} {char_.origin.y:6.2f})'
                            + f' quad=('
                                +  f'ul=({char_.quad.ul.x:6.2f} {char_.quad.ul.y:6.2f})'
                                + f' ur=({char_.quad.ur.x:6.2f} {char_.quad.ur.y:6.2f})'
                                + f' ll=({char_.quad.ll.x:6.2f} {char_.quad.ll.y:6.2f})'
                                + f' lr=({char_.quad.lr.x:6.2f} {char_.quad.lr.y:6.2f})'
                                + f')'
                            + f' size={char_.size:6.2f}'
                            + f' font=('
                                +  f'is_mono={char_.font.flags.is_mono}'
                                + f' is_bold={char_.font.flags.is_bold}'
                                + f' is_italic={char_.font.flags.is_italic}'
                                + f' ft_substitute={char_.font.flags.ft_substitute}'
                                + f' ft_stretch={char_.font.flags.ft_stretch}'
                                + f' fake_bold={char_.font.flags.fake_bold}'
                                + f' fake_italic={char_.font.flags.fake_italic}'
                                + f' has_opentype={char_.font.flags.has_opentype}'
                                + f' invalid_bbox={char_.font.flags.invalid_bbox}'
                                + f' name={char_.font.name}'
                                + f')'
                            )

document = mupdf.Document('foo.pdf')
show_stext(document)
 

How the build works

Revision 52020-12-16 - JulianSmith

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

C++ and Python APIs for MuPDF

Line: 12 to 12
 

The C++ MuPDF API

Deleted:
<
<
  • 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 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()).
Added:
>
>
  • 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.
Changed:
<
<
    • Some custom methods/constructors.
>
>
    • Some custom class methods and constructors.
 

The Python MuPDF API

Line: 143 to 143
  [SWIG build files]
Added:
>
>

Artifex Licensing

Artifex offers a dual licensing model for MuPDF. Meaning we offer both commercial licenses or the GNU Affero General Public License (AGPL).

While Open Source software may be free to use, that does not mean it is free of obligation. To determine whether your intended use of MuPDF is suitable for the AGPL, please read the full text of the AGPL license agreement on the FSF web site.

With a commercial license from Artifex, you maintain full ownership and control over your products, while allowing you to distribute your products to customers as you wish. You are not obligated to share your proprietary source code and this saves you from having to conform to the requirements and restrictions of the AGPL. For more information, please see our licensing page, or contact our sales team.

 

Please send any questions, comments or suggestions about this page to: julian.smith@artifex.com

Revision 42020-08-26 - JulianSmith

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

C++ and Python APIs for MuPDF

Line: 25 to 25
 

The Python MuPDF API

  • Generated from the C++ MuPDF API's header files.
Changed:
<
<
  • Allow implementation of mutool in Python - see mupdf:scripts/mutool.py and mupdf:scripts/mutool_draw.py.
>
>
  • Allows implementation of mutool in Python - see mupdf:scripts/mutool.py and mupdf:scripts/mutool_draw.py.
 

Building the C++ and Python MuPDF APIs

Line: 37 to 37
 
  • python3-dev version 3.6 or later.
  • SWIG version 3 or 4.
Changed:
<
<
Build C++ and Python MuPDF APIs and run basic tests:
>
>
Build MuPDF shared library, C++ and Python MuPDF APIs, and run basic tests:
 
    git clone --recursive git://git.ghostscript.com/mupdf.git
Line: 82 to 82
  (This enables Python to find the mupdf module, and enables the system dynamic linker to find the shared libraries that implement the underlying C, C++ and Python MuPDF APIs.)
Changed:
<
<
Minimal example Python code:
>
>
Minimal Python code that uses the mupdf module:
 
    import mupdf
    document = mupdf.Document('foo.pdf')
Changed:
<
<
Detailed usage of the Python API can be found in:
>
>
A simple example Python test script (run by scripts/mupdfwrap.py -t) is:
  • scripts/mupdfwrap_test.py
 
Added:
>
>
More detailed usage of the Python API can be found in:
 
  • scripts/mutool.py
  • scripts/mutool_draw.py
Line: 131 to 132
  platform/ c++/ include/
Changed:
<
<
mupdf/ [C++ MuPDF API]
>
>
mupdf/ [C++ MuPDF API header files]
  classes.h exceptions.h functions.h internal.h
Deleted:
<
<

Other internal generated files:

    mupdf/
        build/
        platform/
            c++/
  implementation/
Changed:
<
<
*.cpp [MuPDF C++ implementation]
>
>
*.cpp [MuPDF C++ implementation files]
  python/
Changed:
<
<
[SWIG files]
>
>
[SWIG build files]
 


Revision 32020-08-26 - JulianSmith

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

C++ and Python APIs for MuPDF

Line: 8 to 8
 

API Stability

Changed:
<
<
The C++ and Python MuPDF APIs are currently liable to change.
>
>
The C++ and Python MuPDF APIs are currently an alpha release and liable to change.
 

The C++ MuPDF API

Revision 22020-08-26 - JulianSmith

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

C++ and Python APIs for MuPDF.

>
>

C++ and Python APIs for MuPDF

 
Changed:
<
<

Overview:

>
>

Overview

 
Changed:
<
<

The C++ MuPDF API:

>
>

API Stability

 
Changed:
<
<
  • All C++ API code converts fz_ exceptions into C++ exceptions.
  • All C++ API code uses auto-generated internal per-thread fz_context and do not take fz_context args.
  • We generate C++ wrapper functions for most fz_ and pdf_ functions.
  • We generate C++ class wrappers for most fz_ and pdf_ structs.
  • Class methods provide access to most of the underlying C API functions (except for functions don't take struct args, e.g. fz_strlcpy()).
  • We auto-detect fz_ and pdf_ fns suitable for wrapping as constructors, methods or static methods.
  • We add a small number of extensions beyond the basic C API:
>
>
The C++ and Python MuPDF APIs are currently liable to change.

The C++ MuPDF API

  • 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 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()).
  • Provides a small number of extensions beyond the basic C API:
 
    • Some generated classes have extra support for iteration.
Changed:
<
<
    • We add some custom methods/constructors.
>
>
    • Some custom methods/constructors.
 
Changed:
<
<

The Python MuPDF API:

>
>

The Python MuPDF API

 
Changed:
<
<
  • Python MuPDF API is generated from the C++ MuPDF API's header files.
  • Python MuPDF API is enough to allow implementation of mutool in Python - see mupdf:scripts/mutool.py and mupdf:scripts/mutool_draw.py.
>
>
  • Generated from the C++ MuPDF API's header files.
  • Allow implementation of mutool in Python - see mupdf:scripts/mutool.py and mupdf:scripts/mutool_draw.py.
 
Changed:
<
<

Building the C++ and Python MuPDF APIs:

>
>

Building the C++ and Python MuPDF APIs

 
Changed:
<
<
We require:
  • Linux or OpenBSD.
  • python-clang (version 6 or 7)
  • python3-dev (version 3.6 or later)
  • swig (version 3 or 4)
>
>
Requirements:
 
Changed:
<
<
All building is done with the scripts/mupdfwrap.py script.
>
>
  • Linux or OpenBSD.
  • clang-python version 6 or 7. [For example Debian python-clang, OpenBSD py3-llvm.]
  • python3-dev version 3.6 or later.
  • SWIG version 3 or 4.
 
Changed:
<
<
Build C++ and Python MuPDF APIs and run basic tests with:
>
>
Build C++ and Python MuPDF APIs and run basic tests:

    git clone --recursive git://git.ghostscript.com/mupdf.git
  cd mupdf ./scripts/mupdfwrap.py -b all -t
Changed:
<
<
>
>
 
Changed:
<
<
Debug build:
    cd mupdf
>
>
As above but do a debug build:
  ./scripts/mupdfwrap.py -d build/shared-debug -b all -t
Changed:
<
<
>
>

For more information:

  • Run ./scripts/mupdfwrap.py -h.
  • Read the doc-string at beginning of scripts/mupdfwrap.py.
 
Changed:
<
<
For more details, run ./scripts/mupdfwrap.py -h to see help, or look at the doc-string at beginning of the script directly.
>
>

Building auto-generated documentation

 
Changed:
<
<

Using the Python API:

>
>
Build HTML documentation for the C, C++ and Python APIs (using Doxygen and pydoc):

    ./scripts/mupdfwrap.py --doc all

This will generate these documentation roots:

  • include/html/index.html [C API]
  • platform/c++/include/html/index.html [C++ API]
  • build/shared-release/mupdf.html [Python API]

Note that the content is ultimately all generated from the MuPDF C header file comments.

Using the Python API

  Run python code with:

PYTHONPATH=build/shared-release LD_LIBRARY_PATH=build/shared-release

Changed:
<
<
(This enables Python to find the mupdf module, and enables the system dynamic linker to find the shared libraries that implement the underlying C, C++ and Python MuPDF APIs.)
>
>
(This enables Python to find the mupdf module, and enables the system dynamic linker to find the shared libraries that implement the underlying C, C++ and Python MuPDF APIs.)
 
Changed:
<
<
Example Python code:
>
>
Minimal example Python code:
 
Changed:
<
<
>
>
  import mupdf
Changed:
<
<
document = mupdf.Document("foo.pdf")
>
>
document = mupdf.Document('foo.pdf')
  Detailed usage of the Python API can be found in:
Line: 76 to 95
 
  • scripts/mutool_draw.py
Changed:
<
<

How the build works:

>
>

How the build works

 
Changed:
<
<
Building of MuPDF shared library:
>
>
Building of MuPDF shared library:
 
Changed:
<
<
  • Built by mupdfwrap.py -b m (also included in -b all).
  • This runs make internally.
>
>
  • Runs make internally.
 
Changed:
<
<
mupdfwrap.py 's generation of the C++ MuPDF API:
>
>
Generation of the C++ MuPDF API:
 
Changed:
<
<
  • Uses clang-python to parse MuPDF's C API.
>
>
  • Uses clang-python to parse MuPDF's C API.
 
  • Generates C++ code that wraps the basic C interface.
Changed:
<
<
  • Generates C++ classes for each fz_ struct, and uses various heuristics to define methods that call fz_() functions.
>
>
  • Generates C++ classes for each fz_ struct, and uses various heuristics to define constructors, methods and static methods that call fz_() functions.
 
  • C header file comments are copied into the generated C++ header files.
Changed:
<
<
mupdfwrap.py 's generation of the Python MuPDF API:
>
>
Generation of the Python MuPDF API:
 
Changed:
<
<
  • Based on the C++ MuPDF API.
>
>
  • Based on the C++ MuPDF API.
 
  • Uses SWIG to parse the C++ headers and generate C++ and Python code.
  • Defines some custom-written Python functions and methods.
Changed:
<
<
  • If swig is version 4+, we tell it to propagate C++ comments into the generated Python.
>
>
  • If SWIG is version 4+, C++ comments are converted into Python doc-comments.
 
Changed:
<
<

Generated files:

>
>

Generated files

 
Changed:
<
<
>
>
  mupdf/ build/
Changed:
<
<
shared-release/ [Files needed at runtime.]
>
>
shared-release/ [Files needed at runtime]
  libmupdf.so [implements C MuPDF API] libmupdfcpp.so [implements C++ MuPDF API] mupdf.py [implements Python MuPDF API]
Line: 119 to 136
  exceptions.h functions.h internal.h
Changed:
<
<
>
>
  Other internal generated files:
Changed:
<
<
>
>
  mupdf/ build/ platform/ c++/ implementation/
Changed:
<
<
*.cpp [MuPDF C++ implementation.]
>
>
*.cpp [MuPDF C++ implementation]
  python/
Changed:
<
<
[SWIG files.]
>
>
[SWIG files]
 
Changed:
<
<
>
>
 

Please send any questions, comments or suggestions about this page to: julian.smith@artifex.com

Added:
>
>
META TOPICMOVED by="JulianSmith" date="1598431398" from="Main.MupdfWrappers" to="Main.MuPDFWrap"

Revision 12020-08-25 - JulianSmith

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

C++ and Python APIs for MuPDF.

Overview:

The C++ MuPDF API:

  • All C++ API code converts fz_ exceptions into C++ exceptions.
  • All C++ API code uses auto-generated internal per-thread fz_context and do not take fz_context args.
  • We generate C++ wrapper functions for most fz_ and pdf_ functions.
  • We generate C++ class wrappers for most fz_ and pdf_ structs.
  • Class methods provide access to most of the underlying C API functions (except for functions don't take struct args, e.g. fz_strlcpy()).
  • We auto-detect fz_ and pdf_ fns suitable for wrapping as constructors, methods or static methods.
  • We add a small number of extensions beyond the basic C API:
    • Some generated classes have extra support for iteration.
    • We add some custom methods/constructors.

The Python MuPDF API:

  • Python MuPDF API is generated from the C++ MuPDF API's header files.
  • Python MuPDF API is enough to allow implementation of mutool in Python - see mupdf:scripts/mutool.py and mupdf:scripts/mutool_draw.py.

Building the C++ and Python MuPDF APIs:

We require:

  • Linux or OpenBSD.
  • python-clang (version 6 or 7)
  • python3-dev (version 3.6 or later)
  • swig (version 3 or 4)

All building is done with the scripts/mupdfwrap.py script.

Build C++ and Python MuPDF APIs and run basic tests with:

    cd mupdf
    ./scripts/mupdfwrap.py -b all -t

Debug build:

    cd mupdf
    ./scripts/mupdfwrap.py -d build/shared-debug -b all -t

For more details, run ./scripts/mupdfwrap.py -h to see help, or look at the doc-string at beginning of the script directly.

Using the Python API:

Run python code with:

PYTHONPATH=build/shared-release LD_LIBRARY_PATH=build/shared-release

(This enables Python to find the mupdf module, and enables the system dynamic linker to find the shared libraries that implement the underlying C, C++ and Python MuPDF APIs.)

Example Python code:

    import mupdf
    document = mupdf.Document("foo.pdf")

Detailed usage of the Python API can be found in:

  • scripts/mutool.py
  • scripts/mutool_draw.py

How the build works:

Building of MuPDF shared library:

  • Built by mupdfwrap.py -b m (also included in -b all).
  • This runs make internally.

mupdfwrap.py 's generation of the C++ MuPDF API:

  • Uses clang-python to parse MuPDF's C API.
  • Generates C++ code that wraps the basic C interface.
  • Generates C++ classes for each fz_ struct, and uses various heuristics to define methods that call fz_() functions.
  • C header file comments are copied into the generated C++ header files.

mupdfwrap.py 's generation of the Python MuPDF API:

  • Based on the C++ MuPDF API.
  • Uses SWIG to parse the C++ headers and generate C++ and Python code.
  • Defines some custom-written Python functions and methods.
  • If swig is version 4+, we tell it to propagate C++ comments into the generated Python.

Generated files:

    mupdf/
        build/
            shared-release/ [Files needed at runtime.]
                libmupdf.so [implements C MuPDF API]
                libmupdfcpp.so [implements C++ MuPDF API]
                mupdf.py [implements Python MuPDF API]
                _mupdf.so [implements Python MuPDF API internals]
            shared-debug/
                [as shared-release but debug build]
        platform/
            c++/
                include/
                    mupdf/ [C++ MuPDF API]
                        classes.h
                        exceptions.h
                        functions.h
                        internal.h

Other internal generated files:

    mupdf/
        build/
        platform/
            c++/
                implementation/
                    *.cpp [MuPDF C++ implementation.]
            python/
                [SWIG files.]


Please send any questions, comments or suggestions about this page to: julian.smith@artifex.com

 
This site is powered by the TWiki collaboration platform Powered by PerlCopyright 2014 Artifex Software Inc