API documentation
Constants
Render with Poppler pipeline (true) or Cairo pipeline (false)
Default margins for pdfcrop
. Private, try not to touch!
Interfaces
AbstractDocument
abstract type AbstractDocument
An AbstractDocument
must contain a document as a String or Vector{UInt8} of the full contents of whichever file it is using. It may contain additional fields - for example, PDFDocument
s contain a page number to indicate which page to display, in the case where a PDF has multiple pages.
AbstractDocument
s must implement the following functions:
getdoc(doc::AbstractDocument)::Union{Vector{UInt8}, String}
mimetype(doc::AbstractDocument)::Base.MIME
Cached(doc::AbstractDocument)::AbstractCachedDocument
getdoc(doc::AbstractDocument)::Union{Vector{UInt8}, String}
Return the document data (contents of the file) as a Vector{UInt8}
or String
. This must be the full file, i.e., if it was saved, the file should be immediately openable.
mimetype(::AbstractDocument)::Base.MIME
Return the MIME type of the document. For example, mimetype(::SVGDocument) == MIME("image/svg+xml")
.
Cached(doc::AbstractDocument)::AbstractCachedDocument
Generic interface to cache a document and return it.
AbstractCachedDocument
abstract type AbstractCachedDocument
Cached documents are "loaded" versions of AbstractDocuments, and store a pointer/reference to the loaded version of the document (a Poppler handle for PDFs, or Rsvg handle for SVGs).
They also contain a Cairo surface to which the document has been rendered, as well as a cache of a rasterized PNG and its scale for performance reasons. See the documentation of rasterize
for more.
AbstractCachedDocument
s must implement the AbstractDocument
API, as well as the following:
rasterize(doc::AbstractCachedDocument, [scale::Real = 1])::Matrix{ARGB32}
draw_to_cairo_surface(doc::AbstractCachedDocument, surf::CairoSurface)
update_handle!(doc::AbstractCachedDocument)::<some_handle_type>
rasterize(doc::AbstractCachedDocument, scale::Real = 1)
Render a CachedDocument
to an image at a given scale. This is a convenience function which calls the appropriate rendering function for the document type. Returns an image as a Matrix{ARGB32}
.
draw_to_cairo_surface(doc::AbstractCachedDocument, surf::CairoSurface)
Render a CachedDocument
to a Cairo surface. This is a convenience function which calls the appropriate rendering function for the document type.
update_handle!(doc::AbstractCachedDocument)
Update the internal handle/pointer to the loaded document in a CachedDocument
, and returns it.
This function is used to refresh the handle/pointer to the loaded document in case it has been garbage collected or invalidated. It should return the updated handle/pointer.
For example, in CachedPDF
, this function would reload the PDF document using the doc.doc
field and update the ptr
field with the new Poppler handle, if it is found to be invalid.
Note that this function needs to be implemented for each concrete subtype of AbstractCachedDocument
, as the handle/pointer type and the method to load/update it will be different for different document types (e.g., PDF, SVG, etc.).
Document types
Raw document types
SVGDocument(svg::AbstractString)
A document type which stores an SVG string.
Is converted to CachedSVG
for use in plotting.
PDFDocument(pdf::AbstractString, [page = 0])
A document type which holds a raw PDF as a string.
Is converted to CachedPDF
for use in plotting.
Missing docstring.
Missing docstring for EPSDocument
. Check Documenter's build log for details.
TEXDocument(contents::AbstractString, add_defaults::Bool; requires, preamble, class, classoptions)
This constructor function creates a struct
of type TEXDocument
which can be passed to teximg
. All arguments are to be passed as strings.
If add_defaults
is false
, then we will not automatically add document structure. Note that in this case, keyword arguments will be disregarded and contents
must be a complete LaTeX document.
Available keyword arguments are:
requires
: code which comes beforedocumentclass
in the preamble. Default:raw"\RequirePackage{luatex85}"
.class
: the document class. Default (and what you should use):"standalone"
.classoptions
: the options you should pass to the class, i.e.,\documentclass[$classoptions]{$class}
. Default:"preview, tightpage, 12pt"
.preamble
: arbitrary code for the preamble (between\documentclass
and\begin{document}
). Default:raw"\usepackage{amsmath, xcolor} \pagestyle{empty}"
.
See also CachedTEX
, compile_latex
, etc.
Cached document types
CachedTEX(doc::TEXDocument; kwargs...)
Compile a TEXDocument
, compile it and return the cached TeX object.
A CachedTEX
struct stores the document and its compiled form, as well as some pointers to in-program versions of it. It also stores the page dimensions.
In kwargs
, one can pass anything which goes to the internal function compile_latex
. These are primarily:
engine =
lualatex/
xelatex/...
: the LaTeX engine to use when renderingoptions=
-file-line-error``: the options to pass tolatexmk
.
The constructor stores the following fields:
doc
pdf
ptr
surf
dims
Note
This is a mutable struct
because the pointer to the Poppler handle can change. TODO: make this an immutable struct with a Ref to the handle?? OR maybe even the surface itself...
Note
It is also possible to manually construct a CachedTEX
with nothing
in the doc
field, if you just want to insert a pre-rendered PDF into your figure.
CachedPDF(pdf::PDFDocument)
Holds a PDF document along with a Poppler handle and a Cairo surface to which it has already been rendered.
Usage
CachedPDF(read("path/to/pdf.pdf"), [page = 0])
+CachedPDF(read("path/to/pdf.pdf", String), [page = 0])
+CachedPDF(PDFDocument(...), [page = 0])
Fields
doc
: A reference to thePDFDocument
which is cached here.ptr
: A pointer to the Poppler handle of the PDF. May be randomly GC'ed by Poppler.dims
: The dimensions of the PDF page in points, for ease of access.surf
: A Cairo surface to which Poppler has drawn the PDF. Permanent and cached.image_cache
: A cache for a (rendered_image, scale_factor) pair. This is used to avoid re-rendering the PDF.
CachedSVG(svg::SVGDocument)
Holds an SVG document along with an Rsvg handle and a Cairo surface to which it has already been rendered.
Usage
CachedSVG(read("path/to/svg.svg"))
+CachedSVG(read("path/to/svg.svg", String))
+CachedSVG(SVGDocument(...))
Fields
doc
: The originalSVGDocument
which is cached here, i.e., the text of that SVG.handle
: A pointer to the Rsvg handle of the SVG. May be randomly GC'ed by Rsvg, so is stored as aRef
in case it has to be refreshed.dims
: The dimensions of the SVG in points, for ease of access.surf
: A Cairo surface to which Rsvg has drawn the SVG. Permanent and cached.image_cache
: A cache for a (rendered_image, scale_factor) pair. This is used to avoid re-rendering the PDF.
Missing docstring.
Missing docstring for CachedEPS
. Check Documenter's build log for details.
TODO: add documentation about the LaTeX (compile_latex
), PDF and SVG handling utils here, in case they are of use to anyone.
All other methods and functions
CachedTEX(doc::TEXDocument; kwargs...)
Compile a TEXDocument
, compile it and return the cached TeX object.
A CachedTEX
struct stores the document and its compiled form, as well as some pointers to in-program versions of it. It also stores the page dimensions.
In kwargs
, one can pass anything which goes to the internal function compile_latex
. These are primarily:
engine =
lualatex/
xelatex/...
: the LaTeX engine to use when renderingoptions=
-file-line-error``: the options to pass tolatexmk
.
The constructor stores the following fields:
doc
pdf
ptr
surf
dims
Note
This is a mutable struct
because the pointer to the Poppler handle can change. TODO: make this an immutable struct with a Ref to the handle?? OR maybe even the surface itself...
Note
It is also possible to manually construct a CachedTEX
with nothing
in the doc
field, if you just want to insert a pre-rendered PDF into your figure.
EPSDocument(eps::AbstractString, [page = 0])
A document type which holds an EPS string.
Is converted to CachedPDF
for use in plotting.
TEXDocument(contents::AbstractString, add_defaults::Bool; requires, preamble, class, classoptions)
This constructor function creates a struct
of type TEXDocument
which can be passed to teximg
. All arguments are to be passed as strings.
If add_defaults
is false
, then we will not automatically add document structure. Note that in this case, keyword arguments will be disregarded and contents
must be a complete LaTeX document.
Available keyword arguments are:
requires
: code which comes beforedocumentclass
in the preamble. Default:raw"\RequirePackage{luatex85}"
.class
: the document class. Default (and what you should use):"standalone"
.classoptions
: the options you should pass to the class, i.e.,\documentclass[$classoptions]{$class}
. Default:"preview, tightpage, 12pt"
.preamble
: arbitrary code for the preamble (between\documentclass
and\begin{document}
). Default:raw"\usepackage{amsmath, xcolor} \pagestyle{empty}"
.
See also CachedTEX
, compile_latex
, etc.
RsvgRectangle is a simple struct of: height::Float64 width::Float64 x::Float64 y::Float64
compile_latex(document::AbstractString; tex_engine = CURRENT_TEX_ENGINE[], options = `-file-line-error`)
Compile the given document as a String and return the resulting PDF (also as a String).
crop_pdf(path; margin = (0, 0, 0, 0))
Crop a PDF file using Ghostscript. This alters the crop box but does not actually remove elements.
get_pdf_bbox(path)
Get the bounding box of a PDF file using Ghostscript. Returns a tuple representing the (xmin, ymin, xmax, ymax) of the bounding box.
handle_render_document(cr::CairoContext, handle::RsvgHandle, viewport::_RsvgRectangle)
load_pdf(pdf::String)::Ptr{Cvoid}
+load_pdf(pdf::Vector{UInt8})::Ptr{Cvoid}
Loads a PDF file into a Poppler document handle.
Input may be either a String or a Vector{UInt8}
, each representing the PDF file in memory.
Warn
The String input does NOT represent a filename!
page2img(tex::CachedTeX, page::Int; scale = 1, render_density = 1)
Renders the page
of the given CachedTeX
object to an image, with the given scale
and render_density
.
This function reads the PDF using Poppler and renders it to a Cairo surface, which is then read as an image.
pdf_get_page_size(document::Ptr{Cvoid}, page_number::Int)::Tuple{Float64, Float64}
document
must be a Poppler document handle. Returns a tuple of width, height
.
pdf_num_pages(document::Ptr{Cvoid})::Int
document
must be a Poppler document handle. Returns the number of pages in the document.
pdf_num_pages(filename::String)::Int
Returns the number of pages in a PDF file located at filename
, using the Poppler executable.
Calculate an approximation of a tight rectangle around a 2D rectangle rotated by angle
radians. This is not perfect but works well enough. Check an A vs X to see the difference.
split_pdf(pdf::Union{Vector{UInt8}, String})::Vector{UInt8}
Splits a PDF into its constituent pages, returning a Vector of UInt8 arrays, each representing a page.
The input must be a PDF file, either as a String or as a Vector{UInt8} of the PDF's bytes.
Warn
The input String does NOT represent a filename!
This uses Ghostscript to actually split the PDF and return PDF files. If you just want to render the PDF, use load_pdf
and page2img
instead.
texdoc(contents::AbstractString; kwargs...)
A shorthand for TEXDocument(contents, add_defaults=true; kwargs...)
.
Available keyword arguments are:
requires
: code which comes beforedocumentclass
in the preamble. Default:raw"\RequirePackage{luatex85}"
.class
: the document class. Default (and what you should use):"standalone"
.classoptions
: the options you should pass to the class, i.e.,\documentclass[$classoptions]{$class}
. Default:"preview, tightpage, 12pt"
.preamble
: arbitrary code for the preamble (between\documentclass
and\begin{document}
). Default:raw"\usepackage{amsmath, xcolor} \pagestyle{empty}"
.
teximg(tex; position, ...)
+teximg!(ax_or_scene, tex; position, ...)
This recipe plots rendered TeX
to your Figure or Scene.
There are three types of input you can provide:
Any
String
, which is rendered to LaTeX cognizant of the figure's overall theme,A
TeXDocument
object, which is rendered to LaTeX directly, and can be customized by the user,A
CachedTeX
object, which is a pre-rendered LaTeX document.
tex
may be a single one of these objects, or an array of them.
Attributes
Available attributes and their defaults for MakieCore.Plot{MakieTeX.teximg}
are:
align (:center, :center)
+ depth_shift 0.0f0
+ inspectable true
+ inspector_clear MakieCore.Automatic()
+ inspector_hover MakieCore.Automatic()
+ inspector_label MakieCore.Automatic()
+ markerspace :pixel
+ overdraw false
+ position GeometryBasics.Point{2, Float32}[[0.0, 0.0]]
+ render_density 2
+ rotation Float32[0.0]
+ scale 1.0
+ space :data
+ ssao false
+ transparency false
+ visible true