justpyplot documentation
A fast, lightweight plotting library for real-time visualization.
Basic Usage
import numpy as np
from justpyplot import justpyplot as jplt
x = np.linspace(0, 10, 50)
y = np.sin(x)
# Create plot components
figure, grid, labels, title = jplt.plot(
np.array([x, y]),
title='Sine Wave'
)
# Blend components
final_image = jplt.blend(grid, figure, labels, title)
Installation
pip install justpyplot
API Reference
Main Functions
- justpyplot.justpyplot.blend(*arrays) ndarray[source]
Blends multiple NumPy arrays in the order they are provided.
Parameters: *arrays: Variable length argument list of NumPy arrays to be blended.
Returns: np.ndarray: The blended image if all arrays have the same dimensions,
otherwise returns the first array.
- justpyplot.justpyplot.blend2PIL(arrays, format='PNG') BytesIO[source]
Blend multiple arrays into a PIL image buffer.
Optimized blending function for Jupyter notebook display that converts plot components directly to a PIL image buffer. Requires the Pillow (PIL) package to be installed.
- Parameters:
arrays (tuple of np.ndarray) – Tuple of RGBA arrays to blend: - figure_array: Plot figure components - grid_array: Grid lines and background - labels_array: Axis labels and ticks - title_array: Plot title Each array should have shape (height, width, 4) with RGBA channels
format (str, optional) – Output image format (‘PNG’, ‘JPEG’, etc) (default: ‘PNG’)
- Returns:
Buffer containing the blended image in specified format
- Return type:
BytesIO
- Raises:
ImportError – If Pillow package is not installed
ValueError – If input arrays have different shapes
Examples
>>> plot_arrays = plot(np.array([x, y])) >>> buffer = blend2PIL(plot_arrays) >>> display(Image(buffer.getvalue())) # Jupyter display
- justpyplot.justpyplot.plot(values: array, grid: dict = None, figure: dict = None, title: str = 'Plot', size: Tuple[int, int] = (300, 300), max_len: int = 100) Tuple[ndarray, ndarray, ndarray, ndarray][source]
Generate plot components as separate RGBA numpy arrays.
Creates a plot from input values with customizable grid and figure options. Returns separate arrays for figure, grid, labels and title that can be blended together.
- Parameters:
values (np.array) – 2D array of shape (2, N) containing x and y coordinates
grid (dict, optional) –
Grid customization options:
- nticksint
Number of grid divisions (default: 10)
- colortuple
RGBA color for grid lines (default: (128, 128, 128, 255))
- label_colortuple
RGBA color for axis labels (default: (0, 0, 255, 255))
- label_font_sizefloat
Font size for axis labels (default: 0.4)
- precisionint
Decimal precision for axis labels (default: 2)
- title_marginint
Margin above title in pixels (default: 30)
- y_tick_offsetint
Offset for y-axis labels (default: 5)
- x_tick_offsetint
Offset for x-axis labels (default: 5)
figure (dict, optional) –
Figure customization options:
- scatterbool
Whether to draw points (default: False)
- line_colortuple
RGBA color for lines (default: (255, 0, 0, 255))
- line_widthint
Width of lines in pixels (default: 2)
- point_colortuple
RGBA color for points (default: (0, 255, 0, 255))
- point_radiusint
Radius of points in pixels (default: 3)
- marker_stylestr
Point marker style (‘circle’, ‘cross’, etc) (default: ‘circle’)
- line_thicknessint
Thickness of connecting lines (default: 2)
- line_stylestr
Line style (‘solid’, ‘dashed’, etc) (default: ‘solid’)
title (str, optional) – Plot title (default: ‘Plot’)
size (tuple of int) – (width, height) of plot in pixels (default: (300, 300))
max_len (int, optional) – Maximum number of points to plot (default: 100)
- Returns:
(figure_array, grid_array, labels_array, title_array) Each array has shape (height, width, 4) with RGBA channels
- Return type:
tuple of np.ndarray
Examples
>>> x = np.linspace(0, 10, 50) >>> y = np.sin(x) >>> plot_arrays = plot(np.array([x, y])) >>> final_image = blend(*plot_arrays)
- justpyplot.justpyplot.plot1_at(img_array: ndarray, values: ndarray, title: str = 'Measuring', offset: Tuple[int, int] = (50, 50), size: Tuple[int, int] = (300, 270), point_color: Tuple[int, int, int, int] = (0, 0, 255), r=2, pxdelta: int = 15, grid_color: Tuple[int, int, int, int] = (128, 128, 128), precision: int = 2, default_font_size: float = 0.75, default_font_size_small: float = 0.5, label_color: Tuple[int, int, int, int] = (0, 0, 255), scatter=False, thickness=2, line_color: Tuple[int, int, int, int] = (0, 0, 255), max_len: int = 100) ndarray[source]
Adaptively draw a plot on a NumPy image array.
Plots given values to a given NumPy ndarray, adapting the plot scale and size to fit the input data. Plots fast - no single loop in the code, even if you want to connect points with line segments, measured 20-100x faster then matplotlib. Useful for overlaying real-time plots on images and video frames.
- Args:
img_array: NumPy ndarray to draw the plot on, likely a video frame values: NumPy 1D array of values to plot over time title: Plot title string offset: (x, y) offset tuple for the top-left of plot size: (width, height) tuple for plot size in pixels clr: (R, G, B) tuple for plot color pxdelta: Grid size in pixels precision: Floating point precision for y-axis labels default_font_size: Font size for title default_font_size_small: Font size for axis labels opacity: Opacity value 0-1 for plot elements max_len: Maximum history length for values array
- Returns:
img_array: Image array with overlaid adaptive plot
Text Rendering
- justpyplot.textrender.render_text(text: str, scale: int = 1) ndarray[source]
Render the entire text as a single numpy array.
- justpyplot.textrender.vectorized_text(img_array: ndarray, text: str, position: Tuple[int, int], color: Tuple[int, int, int] = (255, 255, 255), font_size: float = 1, spacing: float = 1.0) ndarray[source]
Render text onto a NumPy array using optimized vectorized operations.
- Args:
img_array (np.ndarray): The input image as a NumPy array. text (str): The text to render. position (Tuple[int, int]): The (x, y) position to place the text. color (Tuple[int, int, int]): RGB color of the text. font_size (float): Font size, similar to CV2’s font scale. spacing (float): Spacing between characters.
- Returns:
np.ndarray: The image array with the text rendered on it.