API documentation

Constants

# MakieTeX.RENDER_DENSITY — Constant.

Default density when rendering images

source

# MakieTeX.RENDER_EXTRASAFE — Constant.

Render with Poppler pipeline (true) or Cairo pipeline (false)

source

# MakieTeX.CURRENT_TEX_ENGINE — Constant.

The current TeX engine which MakieTeX uses.

source

# MakieTeX._PDFCROP_DEFAULT_MARGINS — Constant.

Default margins for pdfcrop. Private, try not to touch!

source

Interfaces

`AbstractDocument`

# MakieTeX.AbstractDocument — Type.

julia

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, PDFDocuments contain a page number to indicate which page to display, in the case where a PDF has multiple pages.

AbstractDocuments must implement the following functions:

getdoc(doc::AbstractDocument)::Union{Vector{UInt8}, String}
mimetype(doc::AbstractDocument)::Base.MIME
Cached(doc::AbstractDocument)::AbstractCachedDocument

source

# MakieTeX.getdoc — Function.

julia

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.

source

# MakieTeX.mimetype — Function.

julia

mimetype(::Type{<: AbstractDocument})::Base.MIME
mimetype(::AbstractDocument)::Base.MIME

Return the MIME type of the document. For example, mimetype(::SVGDocument) == MIME("image/svg+xml").

Note

This is generally defined for the type, and there is a generic overload when passing a constructed object.

source

# MakieTeX.Cached — Function.

julia

Cached(doc::AbstractDocument)::AbstractCachedDocument

Generic interface to cache a document and return it.

source

`AbstractCachedDocument`

# MakieTeX.AbstractCachedDocument — Type.

julia

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.

AbstractCachedDocuments 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>

source

# MakieTeX.rasterize — Function.

julia

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}.

source

# MakieTeX.draw_to_cairo_surface — Function.

julia

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.

source

# MakieTeX.update_handle! — Function.

julia

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.).

source

Document types

Raw document types

# MakieTeX.SVGDocument — Type.

julia

SVGDocument(svg::AbstractString)

A document type which stores an SVG string.

Is converted to CachedSVG for use in plotting.

source

# MakieTeX.PDFDocument — Type.

julia

PDFDocument(pdf::AbstractString, [page = 0])

A document type which holds a raw PDF as a string.

Is converted to CachedPDF for use in plotting.

source

Missing docstring.

Missing docstring for EPSDocument. Check Documenter's build log for details.

# MakieTeX.TEXDocument — Type.

julia

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 before documentclass 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.

source

# MakieTeX.TypstDocument — Type.

julia

TypstDocument(contents::AbstractString, add_defaults::Bool; preamble)

This constructor function creates a struct of type TypstDocument. 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 Typst document.

Available keyword arguments are:

preamble: arbitrary code inserted prior to the contents. Default: "".

See also CachedTypst, compile_typst, etc.

source

Cached document types

# MakieTeX.CachedTEX — Type.

julia

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 rendering
options=-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.

source

# MakieTeX.CachedTypst — Type.

julia

CachedTypst(doc::TypstDocument)

Compile a TypstDocument, compile it and return the cached Typst object.

A CachedTypst 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.

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 CachedTypst with nothing in the doc field, if you just want to insert a pre-rendered PDF into your figure.

source

# MakieTeX.CachedPDF — Type.

julia

CachedPDF(pdf::PDFDocument)

Holds a PDF document along with a Poppler handle and a Cairo surface to which it has already been rendered.

Usage

julia

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 the PDFDocument 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.

source

# MakieTeX.CachedSVG — Type.

julia

CachedSVG(svg::SVGDocument)

Holds an SVG document along with an Rsvg handle and a Cairo surface to which it has already been rendered.

Usage

julia

CachedSVG(read("path/to/svg.svg"))
CachedSVG(read("path/to/svg.svg", String))
CachedSVG(SVGDocument(...))

Fields

doc: The original SVGDocument 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 a Ref 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.

source

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

# MakieTeX.CachedTEX — Method.

julia

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 rendering
options=-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.

source

# MakieTeX.CachedTypst — Method.

julia

CachedTypst(doc::TypstDocument)

Compile a TypstDocument, compile it and return the cached Typst object.

A CachedTypst 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.

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 CachedTypst with nothing in the doc field, if you just want to insert a pre-rendered PDF into your figure.

source

# MakieTeX.EPSDocument — Type.

julia

EPSDocument(eps::AbstractString, [page = 0])

A document type which holds an EPS string.

Is converted to CachedPDF for use in plotting.

source

# MakieTeX.TEXDocument — Method.

julia

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 before documentclass 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.

source

# MakieTeX.TypstDocument — Method.

julia

TypstDocument(contents::AbstractString, add_defaults::Bool; preamble)

This constructor function creates a struct of type TypstDocument. 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 Typst document.

Available keyword arguments are:

preamble: arbitrary code inserted prior to the contents. Default: "".

See also CachedTypst, compile_typst, etc.

source

# MakieTeX._RsvgRectangle — Type.

RsvgRectangle is a simple struct of: height::Float64 width::Float64 x::Float64 y::Float64

source

# MakieTeX.__init__ — Method.

Checks whether the default latex engine is correct

source

# MakieTeX.compile_latex — Method.

julia

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).

source

# MakieTeX.compile_typst — Method.

julia

compile_typst(document::AbstractString)

Compile the given document as a String and return the resulting PDF (also as a String).

source

# MakieTeX.crop_pdf — Method.

julia

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.

source

# MakieTeX.get_pdf_bbox — Method.

julia

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.

source

# MakieTeX.handle_render_document — Method.

handle_render_document(cr::CairoContext, handle::RsvgHandle, viewport::_RsvgRectangle)

source

# MakieTeX.load_pdf — Method.

julia

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!

source

# MakieTeX.page2img — Method.

julia

page2img(ct::Union{CachedTeX, CachedTypst}, page::Int; scale = 1, render_density = 1)

Renders the page of the given CachedTeX or CachedTypst 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.

source

# MakieTeX.pdf_get_page_size — Method.

julia

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.

source

# MakieTeX.pdf_num_pages — Method.

julia

pdf_num_pages(document::Ptr{Cvoid})::Int

document must be a Poppler document handle. Returns the number of pages in the document.

source

# MakieTeX.pdf_num_pages — Method.

julia

pdf_num_pages(filename::String)::Int

Returns the number of pages in a PDF file located at filename, using the Poppler executable.

source

# MakieTeX.rotatedrect — Method.

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.

source

# MakieTeX.split_pdf — Method.

julia

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.

source

# MakieTeX.texdoc — Method.

julia

texdoc(contents::AbstractString; kwargs...)

A shorthand for TEXDocument(contents, add_defaults=true; kwargs...).

Available keyword arguments are:

requires: code which comes before documentclass 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}".

source

# MakieTeX.teximg — Method.

julia

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

source

# MakieTeX.try_tex_engine — Method.

Try to write to engine and see what happens

source

# MakieTeX.typst_doc — Method.

julia

typstdoc(contents::AbstractString; kwargs...)

A shorthand for TypstDocument(contents, add_defaults=true; kwargs...).

Available keyword arguments are:

preamble: arbitrary code inserted prior to the contents. Default: "".

source

API documentation ​

Constants ​

Interfaces ​

AbstractDocument ​

AbstractCachedDocument ​

Document types ​

Raw document types ​

Cached document types ​

All other methods and functions ​

API documentation

Constants

Interfaces

`AbstractDocument`

`AbstractCachedDocument`

Document types

Raw document types

Cached document types

All other methods and functions