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.LTeX Type

MakieTeX.LTeX <: Block

No docstring defined.

Attributes

(type ?MakieTeX.LTeX.x in the REPL for more information about attribute x)

alignmode, halign, height, padding, render_density, rotation, scale, tellheight, tellwidth, tex, valign, visible, width

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)
  clip_planes      MakieCore.Automatic()
  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