API reference
Loading and rendering
- pyplotdesigner.core.design_loader.load_design(import_string)
Decode a layout string into a Design that can be edited before rendering.
Accepts legacy base64 JSON and ppd1: gzip layout strings. Constraints are solved when make_figure_from_design() creates the figure.
- Parameters:
import_string – legacy or compressed layout string
- Returns:
Design
- pyplotdesigner.core.design_loader.make_figure_from_b64(json_b64, **kwargs)
Decode a legacy base64 JSON or ppd1: gzip string representing a design layout, build the Design object, and return a matplotlib Figure and Axes.
- Parameters:
json_b64 – legacy base64 JSON or a ppd1: gzip layout string
kwargs – additional keyword arguments for matplotlib figure creation
- Returns:
(Figure, Dict[str, Axes])
- pyplotdesigner.core.design_loader.make_figure_from_design(design, **kwargs)
Create a matplotlib Figure and Axes from a Design object.
- Parameters:
design – Design object containing layout information
kwargs – additional keyword arguments for matplotlib figure creation
- Returns:
(Figure, Dict[str, Axes])
Design
Element IDs identify objects within a layout; axis names are the keys in the dictionary returned by the rendering functions. get_constant() and get_element() return None for unknown IDs.
- class pyplotdesigner.core.design.Design(figure_width=7, figure_height=5)
The Design is responsible for managing layout elements and constraints, and solving them to compute final positions and dimensions for all elements.
It performs dependency analysis on the constraints to determine a valid evaluation order and applies each constraint once all its input values are resolved.
- add_constant(id=None, value=0.0)
Add a constant value to the design, which can be used in constraints.
- Parameters:
id – unique identifier for the constant (default=None, auto-generated)
value – numeric value of the constant (default=0.0)
- add_constraint(target=None, source=None, multiply=1.0, add_before=0.0, add_after=0.0)
Register a new constraint that governs relationships between element attributes.
target <- add_after + multiply * (source + add_before)
- Parameters:
target – the target element attribute to set (e.g., x, y, width, height)
source – the source element attribute to use as input (optional)
multiply – (default=1.0) multiplier for the source and add_before values
add_before – (default=0.0) value added to the source before multiplication
add_after – (default=0.0) value added after multiplication
- add_element(id=None, type=None, x=0.0, y=0.0, width=1.0, height=1.0, text=None)
Register a new layout element in the design.
- Parameters:
id – identifier for the element
type – element type, such as ‘axis’
x – lower-left x position in inches (default=0.0)
y – lower-left y position in inches (default=0.0)
width – width in inches (default=1.0)
height – height in inches (default=1.0)
text – axis name used as the rendering dictionary key; defaults to id for axes
- Returns:
the newly created Element
- get_b64_string(compressed=False)
Get a layout string, optionally using versioned gzip compression.
- Parameters:
compressed – (default=False) retain legacy output unless requested
- Returns:
legacy base64 JSON or a ppd1: gzip layout string
- get_constant(id)
Return the Constant object identified by its unique ID.
- Parameters:
id – unique identifier of the constant to retrieve
- Returns:
Constant object or None if not found
- get_constraint(target_element, target_attribute)
Get the constraint that sets target_element.target_attribute if it exists.
- Parameters:
target_element – element whose attribute is being set
target_attribute – name of the attribute being set
- Returns:
the constraint if found, otherwise None
- get_element(element_id)
Retrieve a layout element by its unique ID.
- Parameters:
element_id – ID of the element to retrieve
- Returns:
element object if found or None
- get_json_string()
Convert the current design to a JSON string representation.
- Returns:
JSON string representing the design layout
- load(b64string)
Load a Design from legacy base64 JSON or a ppd1: gzip layout string.
- Parameters:
b64string – legacy or compressed layout string representing the design
- remove_element_by_id(element_id)
Safely remove an element from the design, including constraints that reference it.
- Parameters:
element_id – ID of the element to remove
- set_viewport(figure_width=None, figure_height=None)
Set figure dimensions.
- Parameters:
figure_width – (default=None) width of the figure in inches
figure_height – (default=None)height of the figure in inches
- solve(verbose=False)
Solve all registered constraints to compute final positions and dimensions for all elements.
This method will apply constraints in a valid order based on their dependencies, ensuring that all required inputs are resolved before applying each constraint.
- Parameters:
verbose – (default=False) print order of applied constraints
- Raises:
RuntimeError - circular or unsatisfiable constraint detected
Values
Constants and axis properties expose a Variable with get() and set():
design.get_constant('spacing').value.get()
design.get_constant('spacing').value.set(0.4)