API Reference

This page is generated from the current Python docstrings by astro_docs/scripts/generate_api_docs.py. Edit the docstrings in src/tikzfigure/, not this file.

The sections below follow the current public API surface exported from tikzfigure, plus the underlying modules that define the main public classes.

Figure API

from tikzfigure import TikzFigure

TikzFigure

class TikzFigure(FigureParsingMixin, FigurePathMixin, FigureLayoutMixin,
                 FigureRenderMixin, FigureExportMixin)

Main entry point for building TikZ figures programmatically.

Holds layers, variables, colors, and all TikZ primitives. Call generate_tikz to obtain the LaTeX source, compile_pdf to compile it, and savefig / show to export or display the result.

Compilation: By default, compile_pdf, savefig, and show use pdflatex if available on your system. If pdflatex is unavailable, tikzfigure automatically falls back to the latex-on-http web API for compilation. You can explicitly request web-based compilation by passing use_web_compilation=True to these methods. This allows figures to be compiled and rendered without requiring a local LaTeX installation. You can also force this behavior process-wide by setting the TIKZFIGURE_USE_WEB_COMPILATION=1 environment variable. See https://github.com/max-models/tikzfigure for more details.

Attributes:

layers - The LayerCollection holding all drawing layers.
variables - List of Variable objects defined in this figure.
colors - List of (name, Color) pairs defined with colorlet.
ndim - Number of spatial dimensions (2 or 3).
document_setup - Custom LaTeX preamble inserted before \begin{document}.
extra_packages - Extra LaTeX packages to include in the preamble.

TikzFigure.init

def __init__(ndim: int = 2,
             label: str | None = None,
             grid: bool = False,
             tikz_code: str | None = None,
             extra_packages: list | None = None,
             document_setup: str | None = None,
             figure_setup: str | None = None,
             figsize: tuple[float, float] = (10, 6),
             description: str | None = None,
             show_axes: bool = False,
             rows: int | None = None,
             cols: int | None = None) -> None

Initialize a TikzFigure.

Arguments:

ndim - Number of spatial dimensions. Use 2 for standard figures and 3 for pgfplots 3-D axis figures. Defaults to 2.
label - LaTeX \label for the surrounding figure environment. When set, the figure is wrapped in a figure environment.
grid - If True, draw a background grid. Defaults to False.
tikz_code - Existing TikZ code to parse and import. When provided, nodes and paths are reconstructed from the source. Defaults to None.
extra_packages - Additional LaTeX packages to include in the standalone preamble (e.g. ["amsmath"]).
document_setup - Raw LaTeX to insert in the preamble after the standard packages.
figure_setup - TikZ options string placed inside the opening \begin{tikzpicture}[…] bracket.
figsize - (width, height) in centimetres used as a hint for display backends. Defaults to (10, 6).
description - Long description stored for documentation purposes (not emitted in TikZ output).
show_axes - For 3-D figures, if True render the pgfplots axis lines and labels. Defaults to False.
rows - Number of rows in subfigure grid. Must be specified with cols. Defaults to None (no grid).
cols - Number of columns in subfigure grid. Must be specified with rows. Defaults to None (no grid).

TikzFigure.to_dict

def to_dict() -> dict[str, Any]

Serialize this figure to a plain dictionary.

Returns:

A dictionary capturing all figure settings, layers, variables, and colors, suitable for round-tripping via from_dict.

TikzFigure.from_dict

@classmethod
def from_dict(cls, d: dict[str, Any]) -> "TikzFigure"

Reconstruct a TikzFigure from a dictionary.

Arguments:

d - Dictionary as produced by to_dict.

Returns:

A fully restored TikzFigure instance.

TikzFigure.copy

def copy(**overrides: Any) -> "TikzFigure"

Return a deep copy of this figure with optional figure-level overrides.

TikzFigure.configure_spy_scope

def configure_spy_scope(*,
                        mode: SpyScopeMode = "scope",
                        options: OptionInput | None = None,
                        magnification: float | None = None,
                        lens: OptionInput | str | None = None,
                        lens_kwargs: dict[str, Any] | None = None,
                        size: str | object | None = None,
                        width: str | object | None = None,
                        height: str | object | None = None,
                        connect_spies: bool = False,
                        every_spy_in_node_options: OptionInput | None = None,
                        every_spy_in_node_style: dict[str, Any] | None = None,
                        every_spy_on_node_options: OptionInput | None = None,
                        every_spy_on_node_style: dict[str, Any] | None = None,
                        spy_connection_path: str | None = None,
                        **kwargs: Any) -> None

Append figure-wide defaults for subsequent spy commands.

This updates figure_setup with a top-level spy scope configuration, which is useful when several fig.spy(...) calls should share the same magnification, lens, node styling, or connection-path settings.

TikzFigure.add_spy

def add_spy(on: Any,
            *,
            layer: int = 0,
            comment: str | None = None,
            verbose: bool = False,
            options: OptionInput | None = None,
            magnification: float | None = None,
            lens: OptionInput | str | None = None,
            lens_kwargs: dict[str, Any] | None = None,
            size: str | object | None = None,
            width: str | object | None = None,
            height: str | object | None = None,
            connect_spies: bool = False,
            at: Any = None,
            node_label: str | None = None,
            node_options: OptionInput | None = None,
            node_style: dict[str, Any] | None = None,
            **kwargs: Any) -> Spy

Add a top-level \spy command to the figure.

If the figure does not yet have any spy-scope configuration, this method enables a bare spy scope automatically so the generated command works without extra setup.

TikzFigure.add_spy_scope

def add_spy_scope(layer: int = 0,
                  comment: str | None = None,
                  verbose: bool = False,
                  mode: SpyScopeMode = "scope",
                  options: OptionInput | None = None,
                  magnification: float | None = None,
                  lens: OptionInput | str | None = None,
                  lens_kwargs: dict[str, Any] | None = None,
                  size: str | object | None = None,
                  width: str | object | None = None,
                  height: str | object | None = None,
                  connect_spies: bool = False,
                  every_spy_in_node_options: OptionInput | None = None,
                  every_spy_in_node_style: dict[str, Any] | None = None,
                  every_spy_on_node_options: OptionInput | None = None,
                  every_spy_on_node_style: dict[str, Any] | None = None,
                  spy_connection_path: str | None = None,
                  **kwargs: Any) -> Scope

Create a nested scope with local spy defaults.

Use this when spy behavior should apply only to a region of the figure, or when you want nested spy configurations such as an outer outlines scope with an inner overlays scope.

TikzFigure.add_copy

def add_copy(node: Node, verbose: bool = False, **overrides: Any) -> Node

Copy a node into this figure, applying optional constructor-style overrides.

If the source node has an explicit label and no label=... override is provided, the copied node keeps that label and a warning is logged. Nodes whose label was auto-generated by a figure are treated as unlabeled here and receive a fresh node<N> label from this figure.

TikzFigure.add

def add(items: list | tuple | Node,
        layer: int = 0,
        verbose: bool = False) -> None

Add one or more pre-built items to the figure.

Arguments:

items - A single Node or a list/tuple of items to add.
layer - Target layer index. Defaults to 0.
verbose - If True, print a debug message for each insertion.

TikzFigure.colorlet

def colorlet(name: str, color_spec: ColorInput, layer: int = 0) -> Color

Define a named color with \colorlet.

Arguments:

name - The name to assign to the color in LaTeX.
color_spec - A TikZ color specification (e.g. "blue!20").
layer - Layer index (currently unused). Defaults to 0.

Returns:

The Color object that was registered.

TikzFigure.add_package

def add_package(package: str) -> None

Add a LaTeX package to the standalone preamble.

Examples:

fig = TikzFigure() fig.add_package(“amsmath”)

TikzFigure.add_style

def add_style(name: str,
              options: OptionInput | None = None,
              **kwargs: Any) -> TikzStyle

Define or update a named TikZ style at figure scope.

Examples:

fig = TikzFigure() axes = fig.add_style(“axes”) fig.add_style(“important line”, options=[“very thick”]) fig.add_style(“information text”, fill=“red!10”, inner_sep=“1ex”) fig.draw([(0, 0), (1, 0)], options=[axes])

TikzFigure.usetikzlibrary

def usetikzlibrary(*libraries: str) -> None

Examples:

fig = TikzFigure() fig.usetikzlibrary(“calc”, “intersections”) fig.usetikzlibrary(“positioning,quotes”)

TikzFigure.add_node

def add_node(x: (float
                 | int
                 | str
                 | tuple[float | int | str, float | int | str]
                 | tuple[float | int | str, float | int | str,
                         float | int | str]
                 | Node
                 | TikzCoordinate
                 | None) = None,
             y: float | int | str | None = None,
             z: float | int | str | None = None,
             label: str | None = None,
             content: str = "",
             layer: int = 0,
             comment: str | None = None,
             options: OptionInput | None = None,
             verbose: bool = False,
             shape: _Shape = None,
             color: ColorInput | None = None,
             fill: ColorInput | None = None,
             draw: ColorInput | None = None,
             text: ColorInput | None = None,
             opacity: float | None = None,
             fill_opacity: float | None = None,
             draw_opacity: float | None = None,
             text_opacity: float | None = None,
             minimum_width: str | TikzDimension | None = None,
             minimum_height: str | TikzDimension | None = None,
             minimum_size: str | TikzDimension | None = None,
             inner_sep: str | TikzDimension | None = None,
             inner_xsep: str | TikzDimension | None = None,
             inner_ysep: str | TikzDimension | None = None,
             outer_sep: str | TikzDimension | None = None,
             outer_xsep: str | TikzDimension | None = None,
             outer_ysep: str | TikzDimension | None = None,
             line_width: str | TikzDimension | None = None,
             font: str | None = None,
             text_width: str | TikzDimension | None = None,
             text_height: str | TikzDimension | None = None,
             text_depth: str | TikzDimension | None = None,
             align: _Align = None,
             anchor: _Anchor = None,
             above: str | None = None,
             below: str | None = None,
             left: str | None = None,
             right: str | None = None,
             above_left: str | None = None,
             above_right: str | None = None,
             below_left: str | None = None,
             below_right: str | None = None,
             above_of: str | None = None,
             below_of: str | None = None,
             left_of: str | None = None,
             right_of: str | None = None,
             node_distance: str | TikzDimension | None = None,
             rotate: float | None = None,
             xshift: str | TikzDimension | None = None,
             yshift: str | TikzDimension | None = None,
             scale: float | None = None,
             xscale: float | None = None,
             yscale: float | None = None,
             xslant: float | None = None,
             yslant: float | None = None,
             rounded_corners: str | TikzDimension | None = None,
             double: ColorInput | None = None,
             double_distance: str | TikzDimension | None = None,
             dash_pattern: str | None = None,
             dash_phase: str | None = None,
             pattern: _Pattern = None,
             pattern_color: ColorInput | None = None,
             shading: _Shading = None,
             shading_angle: float | None = None,
             left_color: ColorInput | None = None,
             right_color: ColorInput | None = None,
             top_color: ColorInput | None = None,
             bottom_color: ColorInput | None = None,
             inner_color: ColorInput | None = None,
             outer_color: ColorInput | None = None,
             ball_color: ColorInput | None = None,
             regular_polygon_sides: int | None = None,
             star_points: int | None = None,
             star_point_ratio: float | None = None,
             star_point_height: str | None = None,
             shadow_xshift: str | None = None,
             shadow_yshift: str | None = None,
             shadow_color: ColorInput | None = None,
             shadow_opacity: float | None = None,
             shadow_scale: float | None = None,
             pin: str | None = None,
             **kwargs: Any) -> Node

Add a node to the TikZ figure.

Arguments:

x - X-coordinate, a (x, y) / (x, y, z) tuple, or a TikzCoordinate. Use None for relatively positioned nodes.
y - Y-coordinate. Use None when x already provides the full position.
z - Z-coordinate for 3-D figures. Use None when x already provides the full position.
label - Internal TikZ name. Auto-assigned when None.
content - Text or LaTeX content displayed inside the node.
layer - Target layer index. Defaults to 0.
comment - Optional comment prepended in the TikZ output.
options - Flag-style TikZ options (e.g. ["draw", "thick"]).
verbose - If True, print a debug message.
shape - Node shape (e.g. "circle", "rectangle", "diamond").
color - Text color (e.g. "red", "blue!50").
fill - Fill color.
draw - Border/stroke color. Use "none" to hide the border.
text - Alias for text color.
opacity - Overall opacity (0–1).
fill_opacity - Fill opacity (0–1).
draw_opacity - Border opacity (0–1).
text_opacity - Text opacity (0–1).
minimum_width - Minimum node width (e.g. "2cm").
minimum_height - Minimum node height.
minimum_size - Minimum size in both dimensions.
inner_sep - Inner separation between content and border.
inner_xsep - Horizontal inner separation.
inner_ysep - Vertical inner separation.
outer_sep - Outer separation between border and anchors.
outer_xsep - Horizontal outer separation.
outer_ysep - Vertical outer separation.
line_width - Border line width (e.g. "1pt").
font - Font specification (e.g. "\\tiny").
text_width - Text width for automatic line wrapping.
text_height - Explicit text height.
text_depth - Explicit text depth.
align - Text alignment ("left", "center", "right").
anchor - Anchor point (e.g. "center", "north", "south west").
above - Place above, with optional offset (e.g. "5pt").
below - Place below.
left - Place left.
right - Place right.
above_left - Place above-left.
above_right - Place above-right.
below_left - Place below-left.
below_right - Place below-right.
above_of - Place above a named node.
below_of - Place below a named node.
left_of - Place left of a named node.
right_of - Place right of a named node.
node_distance - Distance for relative positioning (e.g. "1cm").
rotate - Rotation angle in degrees.
xshift - Horizontal shift (e.g. "1cm").
yshift - Vertical shift.
scale - Uniform scaling factor.
xscale - Horizontal scaling factor.
yscale - Vertical scaling factor.
xslant - Horizontal slant factor.
yslant - Vertical slant factor.
rounded_corners - Corner rounding radius (e.g. "3pt").
double - Inner color for double borders.
double_distance - Distance between double borders.
dash_pattern - Custom dash pattern (e.g. "on 2pt off 3pt").
dash_phase - Dash pattern starting offset.
pattern - Fill pattern (e.g. "north east lines").
pattern_color - Color for the fill pattern.
shading - Shading type ("axis", "radial", or "ball").
shading_angle - Angle for axis shading.
left_color - Left color for axis shading.
right_color - Right color for axis shading.
top_color - Top color for axis shading.
bottom_color - Bottom color for axis shading.
inner_color - Inner color for radial shading.
outer_color - Outer color for radial shading.
ball_color - Ball color for ball shading.
regular_polygon_sides - Number of sides for shape="regular polygon".
star_points - Number of points for shape="star".
star_point_ratio - Inner-to-outer radius ratio for stars.
star_point_height - Height of star points.
shadow_xshift - Horizontal shadow shift.
shadow_yshift - Vertical shadow shift.
shadow_color - Shadow color.
shadow_opacity - Shadow opacity (0–1).
shadow_scale - Shadow scale factor.
pin - Pin label specification (e.g. "above:text").
**kwargs - Additional TikZ options. Underscores in keys become spaces (e.g. signal_from → signal from).

Returns:

The Node object that was added.

TikzFigure.midpoint

def midpoint(node1: "Node | str",
             node2: "Node | str",
             label: str | None = None,
             layer: int = 0,
             content: str = "",
             **kwargs: Any) -> Node

Add a node at the midpoint between two existing nodes.

Arguments:

node1 - First node object or its label string.
node2 - Second node object or its label string.
label - Label for the new midpoint node. Auto-assigned when None.
layer - Target layer index. Defaults to 0.
content - Text content for the midpoint node.
**kwargs - Additional options forwarded to add_node.

Returns:

The new Node placed at the computed midpoint.

Raises:

ValueError - If either node lacks explicit numeric coordinates.

TikzFigure.add_coordinate

def add_coordinate(label: str,
                   x: (float
                       | int
                       | str
                       | tuple[float | int | str, float | int | str]
                       | tuple[float | int | str, float | int | str,
                               float | int | str]
                       | TikzCoordinate
                       | None) = None,
                   y: float | int | str | None = None,
                   z: float | int | str | None = None,
                   at: str | None = None,
                   layer: int = 0,
                   comment: str | None = None,
                   verbose: bool = False) -> Coordinate

Add a named coordinate point using \coordinate.

A coordinate is an invisible named point — lighter than a tikzfigure.core.node.Node because it has no box, content, or visible styling. Use it to define reusable anchor points, midpoints, or expression-based positions that you can reference in paths and other commands.

Either provide explicit coordinates, or a raw TikZ coordinate expression via at.

Examples::

Fixed point

fig.add_coordinate(“origin”, (0, 0)) fig.draw([“origin”, “A”])

Midpoint using calc (add “calc” to extra_packages)

fig.add_coordinate(“mid”, at=" $(A)!0.5!(B)$ ") fig.draw([“A”, “mid”, “B”])

At a node anchor

fig.add_coordinate(“atip”, at=“A.north”)

Arguments:

label - TikZ name for this coordinate. Used when referencing it in path lists (e.g. ["A", "mid", "B"]).
x - X-coordinate value, a (x, y) / (x, y, z) tuple, or a TikzCoordinate. Must be provided together with y when passed as a scalar. Mutually exclusive with at.
y - Y-coordinate value when passing explicit scalar coordinates. Mutually exclusive with at.
z - Z-coordinate value when passing explicit scalar coordinates. Mutually exclusive with at.
at - Raw TikZ coordinate expression. Examples:
- "$(A)!0.5!(B)$" — midpoint via calc library
- "A.north" — at a node anchor
- "30:2cm" — polar coordinates
Parentheses are added automatically if absent. Mutually exclusive with x/y.
layer - Target layer index. Defaults to 0.
comment - Optional comment prepended in the TikZ output.
verbose - If True, print a debug message after insertion.

Returns:

The newly created Coordinate object.

TikzFigure.add_variable

def add_variable(label: str,
                 value: int | float | str,
                 layer: int | None = 0,
                 comment: str | None = None,
                 verbose: bool = False) -> Variable

Add a pgfmath variable (\pgfmathsetmacro) to the figure.

Variables are emitted at the top of the tikzpicture environment so they can be referenced anywhere in the figure.

Arguments:

label - Variable name (without the leading backslash).
value - Numeric value or PGF math expression string to assign (e.g. 5, "sqrt(2)", "sin(60)").
layer - Layer index (currently unused). Defaults to 0.
comment - Optional comment prepended in the TikZ output.
verbose - Unused; reserved for future debug output.

Returns:

The Variable object that was added.

TikzFigure.declare_function

def declare_function(name: str,
                     args: str | list[str] | tuple[str, ...],
                     body: Any,
                     comment: str | None = None,
                     verbose: bool = False) -> DeclaredFunction

Declare a reusable PGF math function for this figure.

The returned DeclaredFunction is callable, so you can keep a Python reference and later build expressions with f(x) instead of spelling the function name again as a string.

TikzFigure.add_plot

def add_plot(x: Any,
             y: Any | None = None,
             *,
             variable: str = "x",
             domain: tuple[Any, Any] | str | None = None,
             samples: int | None = None,
             smooth: bool = False,
             layer: int = 0,
             comment: str | None = None,
             verbose: bool = False,
             options: OptionInput | None = None,
             tikz_command: str = "draw",
             **kwargs: Any) -> TikzPlot

Add a plain TikZ expression plot outside a pgfplots axis.

TikzFigure.add_raw

def add_raw(tikz_code: str, layer: int = 0, verbose: bool = False) -> RawTikz

Insert a verbatim TikZ code block into the figure.

Arguments:

tikz_code - Raw TikZ source to include verbatim.
layer - Target layer index. Defaults to 0.
verbose - If True, print a debug message after insertion.

Returns:

The RawTikz object that was added.

TikzFigure.arc

def arc(start: PositionInput,
        start_angle: float,
        end_angle: float,
        radius: float | str,
        layer: int = 0,
        comment: str | None = None,
        verbose: bool = False,
        color: ColorInput | None = None,
        fill: ColorInput | None = None,
        draw: ColorInput | None = None,
        text: ColorInput | None = None,
        opacity: float | None = None,
        draw_opacity: float | None = None,
        fill_opacity: float | None = None,
        text_opacity: float | None = None,
        line_width: str | None = None,
        line_cap: _LineCap = None,
        line_join: _LineJoin = None,
        miter_limit: float | None = None,
        dash_pattern: str | None = None,
        dash_phase: str | None = None,
        arrows: ArrowInput | None = None,
        rotate: float | None = None,
        xshift: str | None = None,
        yshift: str | None = None,
        scale: float | None = None,
        xscale: float | None = None,
        yscale: float | None = None,
        **kwargs: Any) -> Arc

Add an arc to the figure.

Arguments:

start - Starting coordinate as an (x, y) / (x, y, z) tuple or TikzCoordinate.
start_angle - Start angle in degrees.
end_angle - End angle in degrees.
radius - Radius of the arc (e.g. "3mm", 0.5).
layer - Target layer index. Defaults to 0.
comment - Optional comment prepended in the TikZ output.
verbose - If True, print a debug message.
color - Line color (e.g. "red", "blue!50").
fill - Fill color for the enclosed area.
draw - Stroke color when different from color.
text - Text color.
opacity - Overall opacity (0–1).
draw_opacity - Stroke opacity (0–1).
fill_opacity - Fill opacity (0–1).
text_opacity - Text opacity (0–1).
line_width - Line width (e.g. "1pt").
line_cap - Line cap style: "butt", "rect", or "round".
line_join - Line join style: "miter", "bevel", or "round".
miter_limit - Miter limit factor for miter joins.
dash_pattern - Custom dash pattern (e.g. "on 2pt off 3pt").
dash_phase - Dash pattern starting offset (e.g. "2pt").
arrows - Arrow specification (e.g. "->", "<->", "*-*").
rotate - Rotation angle in degrees.
xshift - Horizontal shift (e.g. "1cm").
yshift - Vertical shift (e.g. "1cm").
scale - Uniform scaling factor.
xscale - Horizontal scaling factor.
yscale - Vertical scaling factor.
**kwargs - Catch-all for unlisted TikZ options.

Returns:

The Arc object that was added.

TikzFigure.circle

def circle(center: PositionInput,
           radius: float | str,
           layer: int = 0,
           comment: str | None = None,
           verbose: bool = False,
           color: ColorInput | None = None,
           fill: ColorInput | None = None,
           draw: ColorInput | None = None,
           text: ColorInput | None = None,
           opacity: float | None = None,
           draw_opacity: float | None = None,
           fill_opacity: float | None = None,
           text_opacity: float | None = None,
           line_width: str | None = None,
           line_cap: _LineCap = None,
           line_join: _LineJoin = None,
           miter_limit: float | None = None,
           dash_pattern: str | None = None,
           dash_phase: str | None = None,
           rotate: float | None = None,
           xshift: str | None = None,
           yshift: str | None = None,
           scale: float | None = None,
           xscale: float | None = None,
           yscale: float | None = None,
           **kwargs: Any) -> Circle

Add a circle to the figure.

Arguments:

center - Center coordinate as an (x, y) / (x, y, z) tuple or TikzCoordinate.
radius - Radius of the circle (e.g. "5mm", 1.0).
layer - Target layer index. Defaults to 0.
comment - Optional comment prepended in the TikZ output.
verbose - If True, print a debug message.
color - Line color (e.g. "red", "blue!50").
fill - Fill color for the circle.
draw - Stroke color when different from color.
text - Text color.
opacity - Overall opacity (0–1).
draw_opacity - Stroke opacity (0–1).
fill_opacity - Fill opacity (0–1).
text_opacity - Text opacity (0–1).
line_width - Line width (e.g. "1pt").
line_cap - Line cap style: "butt", "rect", or "round".
line_join - Line join style: "miter", "bevel", or "round".
miter_limit - Miter limit factor for miter joins.
dash_pattern - Custom dash pattern (e.g. "on 2pt off 3pt").
dash_phase - Dash pattern starting offset (e.g. "2pt").
rotate - Rotation angle in degrees.
xshift - Horizontal shift (e.g. "1cm").
yshift - Vertical shift (e.g. "1cm").
scale - Uniform scaling factor.
xscale - Horizontal scaling factor.
yscale - Vertical scaling factor.
**kwargs - Catch-all for unlisted TikZ options.

Returns:

The Circle object that was added.

TikzFigure.rectangle

def rectangle(corner1: PositionInput,
              corner2: PositionInput,
              layer: int = 0,
              comment: str | None = None,
              verbose: bool = False,
              color: ColorInput | None = None,
              fill: ColorInput | None = None,
              draw: ColorInput | None = None,
              text: ColorInput | None = None,
              opacity: float | None = None,
              draw_opacity: float | None = None,
              fill_opacity: float | None = None,
              text_opacity: float | None = None,
              line_width: str | None = None,
              line_cap: _LineCap = None,
              line_join: _LineJoin = None,
              miter_limit: float | None = None,
              dash_pattern: str | None = None,
              dash_phase: str | None = None,
              rounded_corners: str | None = None,
              rotate: float | None = None,
              xshift: str | None = None,
              yshift: str | None = None,
              scale: float | None = None,
              xscale: float | None = None,
              yscale: float | None = None,
              **kwargs: Any) -> Rectangle

Add a rectangle to the figure.

Arguments:

corner1 - First corner as an (x, y) / (x, y, z) tuple or TikzCoordinate.
corner2 - Opposite corner as an (x, y) / (x, y, z) tuple or TikzCoordinate.
layer - Target layer index. Defaults to 0.
comment - Optional comment prepended in the TikZ output.
verbose - If True, print a debug message.
color - Line color (e.g. "red", "blue!50").
fill - Fill color for the rectangle.
draw - Stroke color when different from color.
text - Text color.
opacity - Overall opacity (0–1).
draw_opacity - Stroke opacity (0–1).
fill_opacity - Fill opacity (0–1).
text_opacity - Text opacity (0–1).
line_width - Line width (e.g. "1pt").
line_cap - Line cap style: "butt", "rect", or "round".
line_join - Line join style: "miter", "bevel", or "round".
miter_limit - Miter limit factor for miter joins.
dash_pattern - Custom dash pattern (e.g. "on 2pt off 3pt").
dash_phase - Dash pattern starting offset (e.g. "2pt").
rounded_corners - Corner rounding radius (e.g. "5pt").
rotate - Rotation angle in degrees.
xshift - Horizontal shift (e.g. "1cm").
yshift - Vertical shift (e.g. "1cm").
scale - Uniform scaling factor.
xscale - Horizontal scaling factor.
yscale - Vertical scaling factor.
**kwargs - Catch-all for unlisted TikZ options.

Returns:

The Rectangle object that was added.

TikzFigure.ellipse

def ellipse(center: PositionInput,
            x_radius: float | str,
            y_radius: float | str,
            layer: int = 0,
            comment: str | None = None,
            verbose: bool = False,
            color: ColorInput | None = None,
            fill: ColorInput | None = None,
            draw: ColorInput | None = None,
            text: ColorInput | None = None,
            opacity: float | None = None,
            draw_opacity: float | None = None,
            fill_opacity: float | None = None,
            text_opacity: float | None = None,
            line_width: str | None = None,
            line_cap: _LineCap = None,
            line_join: _LineJoin = None,
            miter_limit: float | None = None,
            dash_pattern: str | None = None,
            dash_phase: str | None = None,
            rotate: float | None = None,
            xshift: str | None = None,
            yshift: str | None = None,
            scale: float | None = None,
            xscale: float | None = None,
            yscale: float | None = None,
            **kwargs: Any) -> Ellipse

Add an ellipse to the figure.

Arguments:

center - Center coordinate as an (x, y) / (x, y, z) tuple or TikzCoordinate.
x_radius - Horizontal radius (e.g. "2cm", 1.5).
y_radius - Vertical radius (e.g. "1cm", 0.75).
layer - Target layer index. Defaults to 0.
comment - Optional comment prepended in the TikZ output.
verbose - If True, print a debug message.
color - Line color (e.g. "red", "blue!50").
fill - Fill color for the ellipse.
draw - Stroke color when different from color.
text - Text color.
opacity - Overall opacity (0–1).
draw_opacity - Stroke opacity (0–1).
fill_opacity - Fill opacity (0–1).
text_opacity - Text opacity (0–1).
line_width - Line width (e.g. "1pt").
line_cap - Line cap style: "butt", "rect", or "round".
line_join - Line join style: "miter", "bevel", or "round".
miter_limit - Miter limit factor for miter joins.
dash_pattern - Custom dash pattern (e.g. "on 2pt off 3pt").
dash_phase - Dash pattern starting offset (e.g. "2pt").
rotate - Rotation angle in degrees.
xshift - Horizontal shift (e.g. "1cm").
yshift - Vertical shift (e.g. "1cm").
scale - Uniform scaling factor.
xscale - Horizontal scaling factor.
yscale - Vertical scaling factor.
**kwargs - Catch-all for unlisted TikZ options.

Returns:

The Ellipse object that was added.

TikzFigure.grid

def grid(corner1: PositionInput,
         corner2: PositionInput,
         step: str | None = None,
         layer: int = 0,
         comment: str | None = None,
         verbose: bool = False,
         color: ColorInput | None = None,
         opacity: float | None = None,
         draw_opacity: float | None = None,
         line_width: str | None = None,
         line_cap: _LineCap = None,
         line_join: _LineJoin = None,
         dash_pattern: str | None = None,
         dash_phase: str | None = None,
         rotate: float | None = None,
         xshift: str | None = None,
         yshift: str | None = None,
         scale: float | None = None,
         xscale: float | None = None,
         yscale: float | None = None,
         **kwargs: Any) -> Grid

Add a grid to the figure.

Arguments:

corner1 - First corner as an (x, y) / (x, y, z) tuple or TikzCoordinate.
corner2 - Opposite corner as an (x, y) / (x, y, z) tuple or TikzCoordinate.
step - Grid step size (e.g. "1cm" for uniform, or "0.5cm,1cm" for different x/y steps). Defaults to None (TikZ default of 1cm).
layer - Target layer index. Defaults to 0.
comment - Optional comment prepended in the TikZ output.
verbose - If True, print a debug message.
color - Line color (e.g. "red", "gray!30").
opacity - Overall opacity (0–1).
draw_opacity - Stroke opacity (0–1).
line_width - Line width (e.g. "0.5pt").
line_cap - Line cap style: "butt", "rect", or "round".
line_join - Line join style: "miter", "bevel", or "round".
dash_pattern - Custom dash pattern (e.g. "on 1pt off 1pt").
dash_phase - Dash pattern starting offset (e.g. "1pt").
rotate - Rotation angle in degrees.
xshift - Horizontal shift (e.g. "1cm").
yshift - Vertical shift (e.g. "1cm").
scale - Uniform scaling factor.
xscale - Horizontal scaling factor.
yscale - Vertical scaling factor.
**kwargs - Catch-all for unlisted TikZ options.

Returns:

The Grid object that was added.

TikzFigure.parabola

def parabola(start: PositionInput,
             end: PositionInput,
             bend: PositionInput | None = None,
             layer: int = 0,
             comment: str | None = None,
             verbose: bool = False,
             color: ColorInput | None = None,
             fill: ColorInput | None = None,
             draw: ColorInput | None = None,
             text: ColorInput | None = None,
             opacity: float | None = None,
             draw_opacity: float | None = None,
             fill_opacity: float | None = None,
             text_opacity: float | None = None,
             line_width: str | None = None,
             line_cap: _LineCap = None,
             line_join: _LineJoin = None,
             miter_limit: float | None = None,
             dash_pattern: str | None = None,
             dash_phase: str | None = None,
             arrows: ArrowInput | None = None,
             rotate: float | None = None,
             xshift: str | None = None,
             yshift: str | None = None,
             scale: float | None = None,
             xscale: float | None = None,
             yscale: float | None = None,
             **kwargs: Any) -> Parabola

Add a parabola to the figure.

Arguments:

start - Starting coordinate as an (x, y) / (x, y, z) tuple or TikzCoordinate.
end - Ending coordinate as an (x, y) / (x, y, z) tuple or TikzCoordinate.
bend - Bend point as an (x, y) / (x, y, z) tuple or TikzCoordinate. If None, uses TikZ default.
layer - Target layer index. Defaults to 0.
comment - Optional comment prepended in the TikZ output.
verbose - If True, print a debug message.
color - Line color (e.g. "red", "blue!50").
fill - Fill color for the parabola.
draw - Stroke color when different from color.
text - Text color.
opacity - Overall opacity (0–1).
draw_opacity - Stroke opacity (0–1).
fill_opacity - Fill opacity (0–1).
text_opacity - Text opacity (0–1).
line_width - Line width (e.g. "1pt").
line_cap - Line cap style: "butt", "rect", or "round".
line_join - Line join style: "miter", "bevel", or "round".
miter_limit - Miter limit factor for miter joins.
dash_pattern - Custom dash pattern (e.g. "on 2pt off 3pt").
dash_phase - Dash pattern starting offset (e.g. "2pt").
arrows - Arrow specification (e.g. "->", "<->", "*-*").
rotate - Rotation angle in degrees.
xshift - Horizontal shift (e.g. "1cm").
yshift - Vertical shift (e.g. "1cm").
scale - Uniform scaling factor.
xscale - Horizontal scaling factor.
yscale - Vertical scaling factor.
**kwargs - Catch-all for unlisted TikZ options.

Returns:

The Parabola object that was added.

TikzFigure.line

def line(start: PositionInput,
         end: PositionInput,
         layer: int = 0,
         comment: str | None = None,
         verbose: bool = False,
         options: OptionInput | None = None,
         color: ColorInput | None = None,
         text: ColorInput | None = None,
         opacity: float | None = None,
         draw_opacity: float | None = None,
         line_width: str | None = None,
         line_cap: _LineCap = None,
         line_join: _LineJoin = None,
         miter_limit: float | None = None,
         dash_pattern: str | None = None,
         dash_phase: str | None = None,
         arrows: ArrowInput | None = None,
         rotate: float | None = None,
         xshift: str | None = None,
         yshift: str | None = None,
         scale: float | None = None,
         xscale: float | None = None,
         yscale: float | None = None,
         **kwargs: Any) -> Line

Add a line segment to the figure.

Arguments:

start - Starting point as an (x, y) / (x, y, z) tuple or TikzCoordinate.
end - Ending point as an (x, y) / (x, y, z) tuple or TikzCoordinate.
layer - Target layer index. Defaults to 0.
comment - Optional comment prepended in the TikZ output.
verbose - If True, print a debug message.
options - Flag-style TikZ options without values (e.g. ["dashed", "thick"]).
color - Line color (e.g. "red", "blue!50").
text - Text color.
opacity - Overall opacity (0–1).
draw_opacity - Stroke opacity (0–1).
line_width - Line width (e.g. "1pt").
line_cap - Line cap style: "butt", "rect", or "round".
line_join - Line join style: "miter", "bevel", or "round".
miter_limit - Miter limit factor for miter joins.
dash_pattern - Custom dash pattern (e.g. "on 2pt off 3pt").
dash_phase - Dash pattern starting offset (e.g. "2pt").
arrows - Arrow specification (e.g. "->", "<->", "*-*").
rotate - Rotation angle in degrees.
xshift - Horizontal shift (e.g. "1cm").
yshift - Vertical shift (e.g. "1cm").
scale - Uniform scaling factor.
xscale - Horizontal scaling factor.
yscale - Vertical scaling factor.
**kwargs - Catch-all for unlisted TikZ options.

Returns:

The Line object that was added.

TikzFigure.polygon

def polygon(center: PositionInput,
            radius: float | str,
            sides: int,
            rotation: float = 0,
            layer: int = 0,
            comment: str | None = None,
            verbose: bool = False,
            color: ColorInput | None = None,
            fill: ColorInput | None = None,
            draw: ColorInput | None = None,
            text: ColorInput | None = None,
            opacity: float | None = None,
            draw_opacity: float | None = None,
            fill_opacity: float | None = None,
            text_opacity: float | None = None,
            line_width: str | None = None,
            line_cap: _LineCap = None,
            line_join: _LineJoin = None,
            miter_limit: float | None = None,
            dash_pattern: str | None = None,
            dash_phase: str | None = None,
            rotate: float | None = None,
            xshift: str | None = None,
            yshift: str | None = None,
            scale: float | None = None,
            xscale: float | None = None,
            yscale: float | None = None,
            **kwargs: Any) -> Polygon

Add a regular polygon to the figure.

Arguments:

center - Center coordinate as an (x, y) / (x, y, z) tuple or TikzCoordinate.
radius - Distance from center to vertices.
sides - Number of sides (must be >= 3).
rotation - Rotation angle in degrees. Defaults to 0.
layer - Target layer index. Defaults to 0.
comment - Optional comment prepended in the TikZ output.
verbose - If True, print a debug message.
color - Line color (e.g. "red", "blue!50").
fill - Fill color for the polygon.
draw - Stroke color when different from color.
text - Text color.
opacity - Overall opacity (0–1).
draw_opacity - Stroke opacity (0–1).
fill_opacity - Fill opacity (0–1).
text_opacity - Text opacity (0–1).
line_width - Line width (e.g. "1pt").
line_cap - Line cap style: "butt", "rect", or "round".
line_join - Line join style: "miter", "bevel", or "round".
miter_limit - Miter limit factor for miter joins.
dash_pattern - Custom dash pattern (e.g. "on 2pt off 3pt").
dash_phase - Dash pattern starting offset (e.g. "2pt").
rotate - Rotation angle in degrees.
xshift - Horizontal shift (e.g. "1cm").
yshift - Vertical shift (e.g. "1cm").
scale - Uniform scaling factor.
xscale - Horizontal scaling factor.
yscale - Vertical scaling factor.
**kwargs - Catch-all for unlisted TikZ options.

Returns:

The Polygon object that was added.

TikzFigure.triangle

def triangle(center: PositionInput,
             radius: float | str,
             rotation: float = 0,
             layer: int = 0,
             comment: str | None = None,
             verbose: bool = False,
             color: ColorInput | None = None,
             fill: ColorInput | None = None,
             draw: ColorInput | None = None,
             text: ColorInput | None = None,
             opacity: float | None = None,
             draw_opacity: float | None = None,
             fill_opacity: float | None = None,
             text_opacity: float | None = None,
             line_width: str | None = None,
             **kwargs: Any) -> Triangle

Add an equilateral triangle to the figure.

Arguments:

center - Center coordinate as an (x, y) / (x, y, z) tuple or TikzCoordinate.
radius - Distance from center to vertices.
rotation - Rotation angle in degrees. Defaults to 0.
layer - Target layer index. Defaults to 0.
comment - Optional comment prepended in the TikZ output.
verbose - If True, print a debug message.
color - Line color (e.g. "red", "blue!50").
fill - Fill color for the triangle.
draw - Stroke color when different from color.
text - Text color.
opacity - Overall opacity (0–1).
draw_opacity - Stroke opacity (0–1).
fill_opacity - Fill opacity (0–1).
text_opacity - Text opacity (0–1).
line_width - Line width (e.g. "1pt").
**kwargs - Catch-all for unlisted TikZ options.

Returns:

The Triangle object that was added.

TikzFigure.square

def square(center: PositionInput,
           radius: float | str,
           rotation: float = 45,
           layer: int = 0,
           comment: str | None = None,
           verbose: bool = False,
           color: ColorInput | None = None,
           fill: ColorInput | None = None,
           draw: ColorInput | None = None,
           text: ColorInput | None = None,
           opacity: float | None = None,
           draw_opacity: float | None = None,
           fill_opacity: float | None = None,
           text_opacity: float | None = None,
           line_width: str | None = None,
           **kwargs: Any) -> Square

Add a square to the figure.

Arguments:

center - Center coordinate as an (x, y) / (x, y, z) tuple or TikzCoordinate.
radius - Distance from center to vertices (corner-to-center distance).
rotation - Rotation angle in degrees. Defaults to 45 (axis-aligned).
layer - Target layer index. Defaults to 0.
comment - Optional comment prepended in the TikZ output.
verbose - If True, print a debug message.
color - Line color (e.g. "red", "blue!50").
fill - Fill color for the square.
draw - Stroke color when different from color.
text - Text color.
opacity - Overall opacity (0–1).
draw_opacity - Stroke opacity (0–1).
fill_opacity - Fill opacity (0–1).
text_opacity - Text opacity (0–1).
line_width - Line width (e.g. "1pt").
**kwargs - Catch-all for unlisted TikZ options.

Returns:

The Square object that was added.

TikzFigure.plot3d

def plot3d(x: list[float],
           y: list[float],
           z: list[float],
           layer: int = 0,
           comment: str | None = None,
           center: bool = False,
           verbose: bool = False,
           **kwargs: Any) -> Plot3D

Add a 3-D data plot with \addplot3.

Arguments:

x - List of x-coordinate values.
y - List of y-coordinate values.
z - List of z-coordinate values.
layer - Target layer index. Defaults to 0.
comment - Optional comment prepended in the TikZ output.
center - If True, connect through .center anchors.
verbose - If True, print a debug message.
**kwargs - Additional pgfplots options (e.g. mark="*").

Returns:

The Plot3D object that was added.

TikzFigure.axis2d

def axis2d(xlabel: str = "",
           ylabel: str = "",
           xlim: tuple[float, float] | None = None,
           ylim: tuple[float, float] | None = None,
           xlog: bool = False,
           ylog: bool = False,
           grid: bool | str = True,
           width: str | int | float | None = None,
           height: str | int | float | None = None,
           layer: int = 0,
           comment: str | None = None,
           **kwargs: Any) -> Axis2D

Create and register a 2D axis.

Arguments:

xlabel - Label for x-axis. Defaults to "".
ylabel - Label for y-axis. Defaults to "".
xlim - (min, max) tuple for x-axis limits, or None for auto.
ylim - (min, max) tuple for y-axis limits, or None for auto.
xlog - Whether to use logarithmic scaling on the x-axis.
ylog - Whether to use logarithmic scaling on the y-axis.
grid - Enable grid lines. Pass True / False for the usual pgfplots values or a string such as "major".
width - Width of the axis as a string (e.g., “8cm”), number in cm, or None for auto. Defaults to None.
height - Height of the axis as a string (e.g., “6cm”), number in cm, or None for auto. Defaults to None.
layer - Layer index (for metadata; axes render after all layers).
comment - Optional comment prepended in TikZ output.
**kwargs - Additional pgfplots axis options.

Returns:

The newly created Axis2D object.

TikzFigure.add_loop

def add_loop(variable: str,
             values: list[Any] | tuple[Any, ...] | range,
             layer: int = 0,
             comment: str | None = None,
             verbose: bool = False) -> Loop

Add a \foreach loop to the figure.

Arguments:

variable - Loop variable name (without the leading backslash), e.g. "i" produces \foreach \i in {...}.
values - Sequence of values to iterate over.
layer - Target layer index. Defaults to 0.
comment - Optional comment prepended in the TikZ output.
verbose - If True, print a debug message.

Returns:

The Loop context manager. Add nodes and paths inside a with block or by calling methods on the returned object.

TikzFigure.add_scope

def add_scope(layer: int = 0,
              comment: str | None = None,
              options: OptionInput | None = None,
              verbose: bool = False,
              **kwargs: Any) -> Scope

Add a TikZ scope block with local options to the figure.

TikzFigure.document_setup

@property
def document_setup() -> str | None

Raw LaTeX inserted in the preamble before \begin{document}.

TikzFigure.extra_packages

@property
def extra_packages() -> list[str] | None

Extra LaTeX packages included in the standalone preamble.

TikzFigure.named_styles

@property
def named_styles() -> list[dict[str, Any]]

Named TikZ styles defined at figure scope.

TikzFigure.tikz_libraries

@property
def tikz_libraries() -> list[str]

TikZ libraries loaded in standalone output via \usetikzlibrary.

TikzFigure.ndim

@property
def ndim() -> int

Number of spatial dimensions (2 or 3).

TikzFigure.layers

@property
def layers() -> LayerCollection

The LayerCollection holding all drawing layers.

TikzFigure.colors

@property
def colors() -> list[tuple[str, Color]]

List of (name, Color) pairs defined with colorlet.

TikzFigure.variables

@property
def variables() -> list

List of Variable objects defined in this figure.

TikzFigure.declared_functions

@property
def declared_functions() -> list[DeclaredFunction]

List of declared PGF functions available in this figure.

TikzFigure.axes

@property
def axes() -> list[Axis2D]

List of Axis2D objects created in this figure.

TikzFigure.subfigure_axes

@property
def subfigure_axes() -> list[tuple[Axis2D, float]]

List of subfigure axes with widths.

TikzFigure.repr

def __repr__() -> str

Return the generated TikZ source as the object representation.

TikzFigure.str

def __str__() -> str

Return the generated TikZ source as a string.

Node API

from tikzfigure import Node

Node

class Node(TikzObject)

A TikZ node with an optional position, content, and styling options.

Accepts the same TikZ options as TikzFigure.add_node. Refer to that method for the full parameter reference.

Attributes:

x - X-coordinate of the node, or None for relatively positioned nodes.
y - Y-coordinate of the node, or None for relatively positioned nodes.
z - Z-coordinate for 3-D figures, or None for 2-D figures.
ndim - Number of spatial dimensions (2 or 3).
content - Text or LaTeX content displayed inside the node.

Node.init

def __init__(x: (CoordinateValue
                 | CoordinateTuple2D
                 | CoordinateTuple3D
                 | TikzCoordinate
                 | None) = None,
             y: CoordinateValue | None = None,
             z: CoordinateValue | None = None,
             label: str = "",
             content: str = "",
             comment: str | None = None,
             layer: int = 0,
             options: OptionInput | None = None,
             shape: _Shape = None,
             color: ColorInput | None = None,
             fill: ColorInput | None = None,
             draw: ColorInput | None = None,
             text: ColorInput | None = None,
             opacity: float | None = None,
             fill_opacity: float | None = None,
             draw_opacity: float | None = None,
             text_opacity: float | None = None,
             minimum_width: str | None = None,
             minimum_height: str | None = None,
             minimum_size: str | None = None,
             inner_sep: str | None = None,
             inner_xsep: str | None = None,
             inner_ysep: str | None = None,
             outer_sep: str | None = None,
             outer_xsep: str | None = None,
             outer_ysep: str | None = None,
             line_width: str | None = None,
             font: str | None = None,
             text_width: str | None = None,
             text_height: str | None = None,
             text_depth: str | None = None,
             align: _Align = None,
             anchor: _Anchor = None,
             above: str | None = None,
             below: str | None = None,
             left: str | None = None,
             right: str | None = None,
             above_left: str | None = None,
             above_right: str | None = None,
             below_left: str | None = None,
             below_right: str | None = None,
             above_of: str | None = None,
             below_of: str | None = None,
             left_of: str | None = None,
             right_of: str | None = None,
             node_distance: str | None = None,
             rotate: float | None = None,
             xshift: str | None = None,
             yshift: str | None = None,
             scale: float | None = None,
             xscale: float | None = None,
             yscale: float | None = None,
             xslant: float | None = None,
             yslant: float | None = None,
             rounded_corners: str | None = None,
             double: ColorInput | None = None,
             double_distance: str | None = None,
             dash_pattern: str | None = None,
             dash_phase: str | None = None,
             pattern: _Pattern = None,
             pattern_color: ColorInput | None = None,
             shading: _Shading = None,
             shading_angle: float | None = None,
             left_color: ColorInput | None = None,
             right_color: ColorInput | None = None,
             top_color: ColorInput | None = None,
             bottom_color: ColorInput | None = None,
             inner_color: ColorInput | None = None,
             outer_color: ColorInput | None = None,
             ball_color: ColorInput | None = None,
             regular_polygon_sides: int | None = None,
             star_points: int | None = None,
             star_point_ratio: float | None = None,
             star_point_height: str | None = None,
             shadow_xshift: str | None = None,
             shadow_yshift: str | None = None,
             shadow_color: ColorInput | None = None,
             shadow_opacity: float | None = None,
             shadow_scale: float | None = None,
             pin: str | None = None,
             **kwargs: Any) -> None

Initialize a Node.

Accepts the same TikZ options as TikzFigure.add_node. Refer to that method for the full parameter reference.

Arguments:

x - X-coordinate, a (x, y) / (x, y, z) tuple, or a TikzCoordinate. Use None for relatively positioned nodes.
y - Y-coordinate. Use None when x already provides the full position.
z - Z-coordinate for 3-D figures. Use None when x already provides the full position.
label - Internal TikZ name for this node. Defaults to "".
content - Text or LaTeX content displayed inside the node.
comment - Optional comment prepended in the TikZ output.
layer - Layer index. Defaults to 0.
options - Flag-style TikZ options (e.g. ["draw", "thick"]).
shape - Node shape (e.g. "circle", "rectangle").
color - Text color.
fill - Fill color.
draw - Border/stroke color.
text - Alias for text color.
opacity - Overall opacity (0–1).
fill_opacity - Fill opacity (0–1).
draw_opacity - Border opacity (0–1).
text_opacity - Text opacity (0–1).
minimum_width - Minimum node width (e.g. "2cm").
minimum_height - Minimum node height.
minimum_size - Minimum size in both dimensions.
inner_sep - Inner separation between content and border.
inner_xsep - Horizontal inner separation.
inner_ysep - Vertical inner separation.
outer_sep - Outer separation between border and anchors.
outer_xsep - Horizontal outer separation.
outer_ysep - Vertical outer separation.
line_width - Border line width (e.g. "1pt").
font - Font specification (e.g. "\\tiny").
text_width - Text width for automatic line wrapping.
text_height - Explicit text height.
text_depth - Explicit text depth.
align - Text alignment ("left", "center", "right").
anchor - Anchor point (e.g. "center", "north").
above - Place above, with optional offset (e.g. "5pt").
below - Place below.
left - Place left.
right - Place right.
above_left - Place above-left.
above_right - Place above-right.
below_left - Place below-left.
below_right - Place below-right.
above_of - Place above a named node.
below_of - Place below a named node.
left_of - Place left of a named node.
right_of - Place right of a named node.
node_distance - Distance for relative positioning (e.g. "1cm").
rotate - Rotation angle in degrees.
xshift - Horizontal shift (e.g. "1cm").
yshift - Vertical shift.
scale - Uniform scaling factor.
xscale - Horizontal scaling factor.
yscale - Vertical scaling factor.
xslant - Horizontal slant factor.
yslant - Vertical slant factor.
rounded_corners - Corner rounding radius (e.g. "3pt").
double - Inner color for double borders.
double_distance - Distance between double borders.
dash_pattern - Custom dash pattern (e.g. "on 2pt off 3pt").
dash_phase - Dash pattern starting offset.
pattern - Fill pattern (e.g. "north east lines").
pattern_color - Color for the fill pattern.
shading - Shading type ("axis", "radial", "ball").
shading_angle - Angle for axis shading.
left_color - Left color for axis shading.
right_color - Right color for axis shading.
top_color - Top color for axis shading.
bottom_color - Bottom color for axis shading.
inner_color - Inner color for radial shading.
outer_color - Outer color for radial shading.
ball_color - Ball color for ball shading.
regular_polygon_sides - Number of sides for shape="regular polygon".
star_points - Number of points for shape="star".
star_point_ratio - Inner-to-outer radius ratio for stars.
star_point_height - Height of star points.
shadow_xshift - Horizontal shadow shift.
shadow_yshift - Vertical shadow shift.
shadow_color - Shadow color.
shadow_opacity - Shadow opacity (0–1).
shadow_scale - Shadow scale factor.
pin - Pin label specification (e.g. "above:text").
**kwargs - Additional TikZ options not listed above. Underscores in keys become spaces in the output.

Node.x

@property
def x() -> CoordinateValue | None

X-coordinate, or None for relatively positioned nodes.

Node.y

@property
def y() -> CoordinateValue | None

Y-coordinate, or None for relatively positioned nodes.

Node.z

@property
def z() -> CoordinateValue | None

Z-coordinate for 3-D figures, or None for 2-D figures.

Node.coordinate

@property
def coordinate() -> TikzCoordinate | None

TikzCoordinate for this node, or None for relatively positioned nodes.

Node.position

@property
def position() -> TikzCoordinate | None

Alias for coordinate for geometric operations.

Node.ndim

@property
def ndim() -> int

Number of spatial dimensions (2 or 3).

Node.center

@property
def center() -> str

Anchor point for the center of the node.

Node.content

@property
def content() -> str

Text or LaTeX content displayed inside this node.

Node.copy

def copy(**overrides: Any) -> "Node"

Return a copy of this node with optional constructor-style overrides.

Node.to_vector

def to_vector() -> TikzVector

Interpret this node position as a vector from the origin.

Node.vector_to

def vector_to(other: "Node | TikzCoordinate") -> TikzVector

Return the vector from this node to another node or point.

Node.distance_to

def distance_to(other: "Node | TikzCoordinate") -> float

Return the Euclidean distance to another node or point.

Node.translate

def translate(vector: VectorInput) -> TikzCoordinate

Return the translated point for this node.

Node.to

def to(target: "Node | Coordinate",
       options: OptionInput | None = None,
       **kwargs: Any) -> "NodePathBuilder"

Create a path builder for a segment from this node to target.

The returned builder always starts with self and records the segment options for the edge from self to target. Chain additional .to(...) or .arc(...) calls on the builder to add more path segments. Only Node and Coordinate targets are accepted by .to(...).

Node.to_tikz

def to_tikz(output_unit: str | None = None) -> str

Generate the TikZ \node command for this node.

Returns:

A TikZ \node command string ending with a newline, optionally preceded by a comment line.

Node.to_dict

def to_dict() -> dict[str, Any]

Serialize this node to a plain dictionary.

Returns:

A dictionary with type, x, y, z, content, and all base-class keys.

Node.from_dict

@classmethod
def from_dict(cls, d: dict[str, Any]) -> "Node"

Reconstruct a Node from a dictionary.

Arguments:

d - Dictionary as produced by to_dict.

Returns:

A new Node instance.

Coordinates and vectors

from tikzfigure import TikzCoordinate, TikzVector

Coordinate

class Coordinate(TikzObject)

A named TikZ coordinate declared with \coordinate.

Unlike a tikzfigure.core.node.Node, a coordinate has no visible output — it simply registers a named point in the figure that can be referenced in paths, calc expressions, or anywhere TikZ accepts a node label.

Common uses:

Defining fixed reference points::

fig.add_coordinate(“origin”, x=0, y=0) fig.draw([“origin”, “A”])

Placing a point at the midpoint between two nodes (requires the calc TikZ library)::

fig.add_coordinate(“mid”, at=" $(A)!0.5!(B)$ ") fig.draw([“A”, “mid”, “B”])

Naming a point at a node anchor::

fig.add_coordinate(“atip”, at=“A.north”)

Attributes:

label - The TikZ name for this coordinate.
x - X value when using absolute positioning, or None.
y - Y value when using absolute positioning, or None.
at - Raw TikZ coordinate expression when using expression positioning, or None.

Coordinate.init

def __init__(label: str,
             x: (CoordinateValue
                 | CoordinateTuple2D
                 | CoordinateTuple3D
                 | "TikzCoordinate"
                 | None) = None,
             y: CoordinateValue | None = None,
             z: CoordinateValue | None = None,
             at: str | None = None,
             layer: int = 0,
             comment: str | None = None) -> None

Initialize a Coordinate.

Provide either explicit coordinates, or a raw TikZ coordinate expression via at.

Arguments:

label - TikZ name for this coordinate, used when referencing it in path lists and other commands.
x - X-coordinate value, a (x, y) / (x, y, z) tuple, or a TikzCoordinate. Must be provided together with y when passed as a scalar. Mutually exclusive with at.
y - Y-coordinate value when passing explicit scalar coordinates. Mutually exclusive with at.
z - Z-coordinate value when passing explicit scalar coordinates. Mutually exclusive with at.
at - Raw TikZ coordinate expression. Examples:
- "$(A)!0.5!(B)$" — midpoint via calc library
- "A.north" — at a node anchor
- "30:2cm" — polar coordinates
If the string does not begin with (, parentheses are added automatically. Mutually exclusive with x/y.
layer - Layer index this coordinate belongs to. Defaults to 0.
comment - Optional comment prepended in the TikZ output.

Raises:

ValueError - If both at and explicit coordinates are supplied, or if neither is supplied.

Coordinate.x

@property
def x() -> CoordinateValue | None

X-coordinate value, or None if using an at expression.

Coordinate.y

@property
def y() -> CoordinateValue | None

Y-coordinate value, or None if using an at expression.

Coordinate.z

@property
def z() -> CoordinateValue | None

Z-coordinate value, or None for 2-D / at coordinates.

Coordinate.to

def to(target: "Node | Coordinate",
       options: "OptionInput | None" = None,
       **kwargs: Any) -> "NodePathBuilder"

Create a path builder for a segment from this coordinate to target.

The returned builder always starts with self and records the segment options for the edge from self to target. Chain additional .to(...) or .arc(...) calls on the builder to add more path segments. Only tikzfigure.core.node.Node and Coordinate targets are accepted by .to(...).

Coordinate.ndim

@property
def ndim() -> int

Number of spatial dimensions (2 or 3).

Coordinate.at

@property
def at() -> str | None

Raw TikZ coordinate expression, or None if using x/y.

Coordinate.to_tikz

def to_tikz(output_unit: str | None = None) -> str

Generate the TikZ \coordinate declaration.

Returns:

A \coordinate (label) at (...); string ending with a newline, optionally preceded by a comment line.

Coordinate.to_dict

def to_dict() -> dict[str, Any]

Serialize this coordinate to a plain dictionary.

Returns:

A dictionary with type, label, x, y, at, layer, and comment keys.

Coordinate.from_dict

@classmethod
def from_dict(cls, d: dict[str, Any]) -> "Coordinate"

Reconstruct a Coordinate from a dictionary.

Arguments:

d - Dictionary as produced by to_dict.

Returns:

A new Coordinate instance.

TikzCoordinate

class TikzCoordinate(TikzObject)

A bare coordinate point (no drawn node) in a TikZ figure.

Used to define path waypoints without producing visible nodes.

Attributes:

x - X-coordinate value (numeric or PGF expression string).
y - Y-coordinate value (numeric or PGF expression string).
z - Z-coordinate value, or None for 2-D figures.
ndim - Number of dimensions (2 or 3).
coordinate - Coordinate as a tuple ready for TikZ output.

TikzCoordinate.init

def __init__(x: CoordinateValue | CoordinateTuple2D | CoordinateTuple3D
             | "TikzCoordinate",
             y: CoordinateValue | None = None,
             z: CoordinateValue | None = None,
             layer: int = 0) -> None

Initialize a TikzCoordinate.

Arguments:

x - X-coordinate value, a (x, y) / (x, y, z) tuple, or an existing TikzCoordinate.
y - Y-coordinate value when passing explicit scalar coordinates.
z - Z-coordinate value when passing explicit scalar coordinates. When provided, the coordinate is treated as 3-D. Defaults to None (2-D).
layer - Layer index this coordinate belongs to. Defaults to 0.

TikzCoordinate.x

@property
def x() -> CoordinateValue

X-coordinate value (numeric or PGF expression string).

TikzCoordinate.y

@property
def y() -> CoordinateValue

Y-coordinate value (numeric or PGF expression string).

TikzCoordinate.z

@property
def z() -> CoordinateValue | None

Z-coordinate value (numeric or PGF expression string), or None for 2-D coordinates.

TikzCoordinate.coordinate

@property
def coordinate() -> tuple[CoordinateValue, ...]

Coordinate as a tuple, either (x, y) or (x, y, z).

TikzCoordinate.ndim

@property
def ndim() -> int

Number of spatial dimensions (2 or 3).

TikzCoordinate.to_vector

def to_vector() -> TikzVector

Interpret this point as a vector from the origin.

TikzCoordinate.vector_to

def vector_to(other: TikzCoordinate) -> TikzVector

Return the vector from this point to another point.

TikzCoordinate.distance_to

def distance_to(other: TikzCoordinate) -> float

Return the Euclidean distance to another point.

TikzCoordinate.translate

def translate(vector: TikzVector) -> TikzCoordinate

Return the translated point.

TikzCoordinate.to_tikz

def to_tikz(output_unit: str | None = None) -> str

Render this coordinate as a TikZ position expression.

TikzCoordinate.to_dict

def to_dict() -> dict[str, Any]

Serialize this coordinate to a plain dictionary.

Returns:

A dictionary with type, x, y, z, and layer keys.

TikzCoordinate.from_dict

@classmethod
def from_dict(cls, d: dict[str, Any]) -> "TikzCoordinate"

Reconstruct a TikzCoordinate from a dictionary.

Arguments:

d - Dictionary as produced by to_dict.

Returns:

A new TikzCoordinate instance.

TikzVector

class TikzVector(TikzCoordinate)

A geometric vector used for linear algebra operations.

TikzVector.dot

def dot(other: TikzVector) -> float

Return the dot product with another vector.

TikzVector.cross

def cross(other: TikzVector) -> TikzVector

Return the cross product with another vector.

TikzVector.norm

def norm() -> float

Return the Euclidean norm.

TikzVector.magnitude

def magnitude() -> float

Return the Euclidean norm.

TikzVector.to_dict

def to_dict() -> dict[str, Any]

Serialize this vector to a plain dictionary.

TikzVector.from_dict

@classmethod
def from_dict(cls, d: dict[str, Any]) -> "TikzVector"

Reconstruct a TikzVector from a dictionary.

Colors

from tikzfigure import colors

Generated by scripts/generate_colors.py. Do not edit by hand.

TikzColor

class TikzColor()

An xcolor-compatible TikZ color expression.

TikzColor.mix

def mix(other: str | "TikzColor" | None = None,
        percent: float | int = 0.5) -> "TikzColor"

Build an xcolor mix like red!50 or red!50!blue.

TikzColor.complement

def complement() -> "TikzColor"

Return the xcolor complementary-expression form.

TikzColor.to_tikz

def to_tikz() -> str

Return the raw xcolor expression.

Units

from tikzfigure import units

TikzDimension

class TikzDimension()

A TikZ dimension value with a unit, e.g. 2.5cm or 10pt.

TikzDimension.to

def to(target_unit: str) -> "TikzDimension"

Convert to another TikZ unit.

Shapes

from tikzfigure import shapes

TikzShape

class TikzShape()

A reusable TikZ node-shape specification.

TikzShape.to_tikz

def to_tikz() -> str

Return the raw TikZ shape specification.

shape

def shape(shape_spec: str) -> TikzShape

Create a custom raw TikZ shape specification.

Styles

from tikzfigure import styles

TikzStyle

class TikzStyle()

A reusable TikZ style token or option fragment.

TikzStyle.to_tikz

def to_tikz() -> str

Return the raw TikZ style fragment.

style

def style(style_spec: str) -> TikzStyle

Create a custom raw TikZ style token.

line_width

def line_width(value: str | int | float | TikzDimension) -> TikzStyle

Build a line width=... option fragment.

rounded_corners

def rounded_corners(radius: str | int | float | TikzDimension) -> TikzStyle

Build a rounded corners=... option fragment.

dash_pattern

def dash_pattern(on: str | int | float | TikzDimension,
                 off: str | int | float | TikzDimension) -> TikzStyle

Build a simple dash pattern=on ... off ... option fragment.

bend_left

def bend_left(angle: float | None = None) -> TikzStyle

Build a bend left option fragment.

bend_right

def bend_right(angle: float | None = None) -> TikzStyle

Build a bend right option fragment.

Arrows

from tikzfigure import arrows

TikzArrow

class TikzArrow()

A reusable TikZ arrow-tip specification.

TikzArrow.to_tikz

def to_tikz() -> str

Return the raw TikZ arrow specification.

tip

def tip(arrow_spec: str) -> TikzArrow

Create a custom raw TikZ arrow specification.

Patterns

from tikzfigure import patterns

TikzPattern

class TikzPattern()

A reusable TikZ fill-pattern specification.

TikzPattern.to_tikz

def to_tikz() -> str

Return the raw TikZ pattern specification.

pattern

def pattern(pattern_spec: str) -> TikzPattern

Create a custom raw TikZ pattern specification.

Decorations

from tikzfigure import decorations

TikzDecoration

class TikzDecoration()

A reusable TikZ path-decoration specification.

TikzDecoration.to_tikz

def to_tikz() -> str

Return the raw TikZ decoration specification.

decoration

def decoration(decoration_spec: str) -> TikzDecoration

Create a custom raw TikZ decoration specification.

Marks

from tikzfigure import marks

TikzMark

class TikzMark()

A reusable pgfplots plot-mark specification.

TikzMark.to_tikz

def to_tikz() -> str

Return the raw pgfplots mark specification.

mark

def mark(mark_spec: str) -> TikzMark

Create a custom raw pgfplots mark specification.

Options

from tikzfigure import options

normalize_options

def normalize_options(options: OptionInput | None) -> list[OptionValue]

Normalize one-or-many option inputs to a plain list.

API Reference

Figure API

TikzFigure

TikzFigure.__init__

TikzFigure.to_dict

TikzFigure.from_dict

TikzFigure.copy

TikzFigure.configure_spy_scope

TikzFigure.add_spy

TikzFigure.add_spy_scope

TikzFigure.add_copy

TikzFigure.add

TikzFigure.colorlet

TikzFigure.add_package

TikzFigure.add_style

TikzFigure.usetikzlibrary

TikzFigure.add_node

TikzFigure.midpoint

TikzFigure.add_coordinate

Fixed point

Midpoint using calc (add “calc” to extra_packages)

At a node anchor

TikzFigure.add_variable

TikzFigure.declare_function

TikzFigure.add_plot

TikzFigure.add_raw

TikzFigure.arc

TikzFigure.circle

TikzFigure.rectangle

TikzFigure.ellipse

TikzFigure.grid

TikzFigure.parabola

TikzFigure.line

TikzFigure.polygon

TikzFigure.triangle

TikzFigure.square

TikzFigure.plot3d

TikzFigure.axis2d

TikzFigure.add_loop

TikzFigure.add_scope

TikzFigure.document_setup

TikzFigure.extra_packages

TikzFigure.named_styles

TikzFigure.tikz_libraries

TikzFigure.ndim

TikzFigure.layers

TikzFigure.colors

TikzFigure.variables

TikzFigure.declared_functions

TikzFigure.axes

TikzFigure.subfigure_axes

TikzFigure.__repr__

TikzFigure.__str__

Node API

Node

Node.__init__

Node.x

Node.y

Node.z

Node.coordinate

Node.position

Node.ndim

Node.center

Node.content

Node.copy

Node.to_vector

Node.vector_to

Node.distance_to

Node.translate

Node.to

Node.to_tikz

Node.to_dict

Node.from_dict

Coordinates and vectors

Coordinate

Coordinate.__init__

Coordinate.x

Coordinate.y

Coordinate.z

Coordinate.to

TikzFigure.init

TikzFigure.repr

TikzFigure.str

Node.init

Coordinate.init

TikzCoordinate.init