Skip to content

whitecanvas.core

new_canvas(backend=None, *, size=None, palette=None)

Create a new canvas with a single cell.

Parameters:

Name Type Description Default
backend Backend or str

Backend name.

 None
size (int, int)

Displaying size of the canvas (in pixels).

 None
palette str or ColormapType

Color palette of the canvas. This color palette will be used to generate colors for the plots.

 None
Source code in whitecanvas\core.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def new_canvas(
    backend: Backend | str | None = None,
    *,
    size: tuple[int, int] | None = None,
    palette: str | ColormapType | None = None,
) -> SingleCanvas:
    """
    Create a new canvas with a single cell.

    Parameters
    ----------
    backend : Backend or str, optional
        Backend name.
    size : (int, int), optional
        Displaying size of the canvas (in pixels).
    palette : str or ColormapType, optional
        Color palette of the canvas. This color palette will be used to generate colors
        for the plots.
    """
    cvs = SingleCanvas._new(palette=palette, backend=backend)
    if size is not None:
        cvs.size = size
    return cvs

new_canvas_3d(backend=None, *, size=None, palette=None)

Create a new 3D canvas with a single cell.

Parameters:

Name Type Description Default
backend Backend or str

Backend name.

 None
size (int, int)

Displaying size of the canvas (in pixels).

 None
palette str or ColormapType

Color palette of the canvas. This color palette will be used to generate colors for the plots.

 None
Source code in whitecanvas\core.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
def new_canvas_3d(
    backend: Backend | str | None = None,
    *,
    size: tuple[int, int] | None = None,
    palette: str | ColormapType | None = None,
) -> SingleCanvas3D:
    """
    Create a new 3D canvas with a single cell.

    Parameters
    ----------
    backend : Backend or str, optional
        Backend name.
    size : (int, int), optional
        Displaying size of the canvas (in pixels).
    palette : str or ColormapType, optional
        Color palette of the canvas. This color palette will be used to generate colors
        for the plots.
    """
    from whitecanvas.canvas.canvas3d._base import SingleCanvas3D

    cvs = SingleCanvas3D._new(palette=palette, backend=backend)
    if size is not None:
        cvs.size = size
    return cvs

new_col(rows=1, *, size=None, backend=None)

Create a new vertical canvas grid with uniform or non-uniform cell sizes.

Source code in whitecanvas\core.py 
137
138
139
140
141
142
143
144
145
146
147
148
def new_col(
    rows: int | Sequence[int] = 1,
    *,
    size: tuple[int, int] | None = None,
    backend: Backend | str | None = None,
) -> CanvasVGrid:
    """Create a new vertical canvas grid with uniform or non-uniform cell sizes."""
    heights = _norm_ratio(rows)
    grid = CanvasVGrid._from_heights(heights, backend=backend)
    if size is not None:
        grid.size = size
    return grid

new_grid(rows=1, cols=1, *, size=None, backend=None)

Create a new canvas grid with uniform or non-uniform cell sizes.

grid = new_grid(2, 3) # 2x3 grid grid = new_grid(2, 3, size=(800, 600)) # 2x3 grid with size 800x600 grid = new_grid([1, 2], [2, 1]) # 2x2 grid with non-uniform sizes

If you want to create a 1D grid, use new_row or new_col instead.

Parameters:

Name Type Description Default
rows int or sequence of int

Number of rows (if an integer is given) or height ratio of the rows (if a sequence of intergers is given).

 1
cols int or sequence of int

Number of columns (if an integer is given) or width ratio of the columns (if a sequence of intergers is given).

 1
size (int, int)

Displaying size of the grid (in pixels).

 None
backend Backend or str

Backend name, such as "matplotlib:qt".

 None

Returns:

Type Description
CanvasGrid

Grid of empty canvases.
Source code in whitecanvas\core.py 
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
def new_grid(
    rows: int | Sequence[int] = 1,
    cols: int | Sequence[int] = 1,
    *,
    size: tuple[int, int] | None = None,
    backend: Backend | str | None = None,
) -> CanvasGrid:
    """
    Create a new canvas grid with uniform or non-uniform cell sizes.

    >>> grid = new_grid(2, 3)  # 2x3 grid
    >>> grid = new_grid(2, 3, size=(800, 600))  # 2x3 grid with size 800x600
    >>> grid = new_grid([1, 2], [2, 1])  # 2x2 grid with non-uniform sizes

    If you want to create a 1D grid, use `new_row` or `new_col` instead.

    Parameters
    ----------
    rows : int or sequence of int, default 1
        Number of rows (if an integer is given) or height ratio of the rows (if a
        sequence of intergers is given).
    cols : int or sequence of int, default 1
        Number of columns (if an integer is given) or width ratio of the columns (if a
        sequence of intergers is given).
    size : (int, int), optional
        Displaying size of the grid (in pixels).
    backend : Backend or str, optional
        Backend name, such as "matplotlib:qt".

    Returns
    -------
    CanvasGrid
        Grid of empty canvases.
    """
    heights = _norm_ratio(rows)
    widths = _norm_ratio(cols)
    grid = CanvasGrid(heights, widths, backend=backend)
    if size is not None:
        grid.size = size
    return grid

new_jointgrid(backend=None, *, loc=(1, 0), size=None, palette=None)

Create a new joint grid.

Parameters:

Name Type Description Default
backend Backend or str

Backend of the canvas.

 None
loc (int, int)

Location of the main canvas. Each integer must be 0 or 1.

 (1, 0)
size (int, int)

Size of the canvas in pixel.

 None
palette colormap type

Color palette used for the canvases.

 None

Returns:

Type Description
JointGrid

Joint grid object.
Source code in whitecanvas\core.py 
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
def new_jointgrid(
    backend: Backend | str | None = None,
    *,
    loc: tuple[_0_or_1, _0_or_1] = (1, 0),
    size: tuple[int, int] | None = None,
    palette: str | ColormapType | None = None,
) -> JointGrid:
    """
    Create a new joint grid.

    Parameters
    ----------
    backend : Backend or str, optional
        Backend of the canvas.
    loc : (int, int), default (1, 0)
        Location of the main canvas. Each integer must be 0 or 1.
    size : (int, int), optional
        Size of the canvas in pixel.
    palette : colormap type, optional
        Color palette used for the canvases.

    Returns
    -------
    JointGrid
        Joint grid object.
    """
    joint = JointGrid(loc, palette=palette, backend=backend)
    if size is not None:
        joint.size = size
    return joint

new_row(cols=1, *, size=None, backend=None)

Create a new horizontal canvas grid with uniform or non-uniform cell sizes.

Source code in whitecanvas\core.py 
123
124
125
126
127
128
129
130
131
132
133
134
def new_row(
    cols: int | Sequence[int] = 1,
    *,
    size: tuple[int, int] | None = None,
    backend: Backend | str | None = None,
) -> CanvasHGrid:
    """Create a new horizontal canvas grid with uniform or non-uniform cell sizes."""
    widths = _norm_ratio(cols)
    grid = CanvasHGrid._from_widths(widths, backend=backend)
    if size is not None:
        grid.size = size
    return grid

read_canvas(path)

Read a canvas from a file.

Parameters:

Name Type Description Default
path str or Path

Path to the file.

 required

Returns:

Type Description
SingleCanvas

Canvas object.
Source code in whitecanvas\core.py 
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
def read_canvas(path: str | Path) -> SingleCanvas:
    """
    Read a canvas from a file.

    Parameters
    ----------
    path : str or Path
        Path to the file.

    Returns
    -------
    SingleCanvas
        Canvas object.
    """
    return SingleCanvas.read_json(path)

read_canvas_3d(path)

Read a 3D canvas from a file.

Parameters:

Name Type Description Default
path str or Path

Path to the file.

 required

Returns:

Type Description
SingleCanvas

Canvas object.
Source code in whitecanvas\core.py 
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
def read_canvas_3d(path: str | Path) -> SingleCanvas3D:
    """
    Read a 3D canvas from a file.

    Parameters
    ----------
    path : str or Path
        Path to the file.

    Returns
    -------
    SingleCanvas
        Canvas object.
    """
    from whitecanvas.canvas.canvas3d._base import SingleCanvas3D

    return SingleCanvas3D.read_json(path)

read_col(path)

Read a column from a file.

Parameters:

Name Type Description Default
path str or Path

Path to the file.

 required

Returns:

Type Description
CanvasVGrid

Column object.
Source code in whitecanvas\core.py 
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
def read_col(path: str | Path) -> CanvasVGrid:
    """
    Read a column from a file.

    Parameters
    ----------
    path : str or Path
        Path to the file.

    Returns
    -------
    CanvasVGrid
        Column object.
    """
    return CanvasVGrid.read_json(path)

read_grid(path)

Read a grid from a file.

Parameters:

Name Type Description Default
path str or Path

Path to the file.

 required

Returns:

Type Description
CanvasGrid

Grid object.
Source code in whitecanvas\core.py 
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
def read_grid(path: str | Path) -> CanvasGrid:
    """
    Read a grid from a file.

    Parameters
    ----------
    path : str or Path
        Path to the file.

    Returns
    -------
    CanvasGrid
        Grid object.
    """
    return CanvasGrid.read_json(path)

read_jointgrid(path)

Read a joint grid from a file.

Parameters:

Name Type Description Default
path str or Path

Path to the file.

 required

Returns:

Type Description
JointGrid

Joint grid object.
Source code in whitecanvas\core.py 
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
def read_jointgrid(path: str | Path) -> JointGrid:
    """
    Read a joint grid from a file.

    Parameters
    ----------
    path : str or Path
        Path to the file.

    Returns
    -------
    JointGrid
        Joint grid object.
    """
    return JointGrid.read_json(path)

read_row(path)

Read a row from a file.

Parameters:

Name Type Description Default
path str or Path

Path to the file.

 required

Returns:

Type Description
CanvasHGrid

Row object.
Source code in whitecanvas\core.py 
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
def read_row(path: str | Path) -> CanvasHGrid:
    """
    Read a row from a file.

    Parameters
    ----------
    path : str or Path
        Path to the file.

    Returns
    -------
    CanvasHGrid
        Row object.
    """
    return CanvasHGrid.read_json(path)

wrap_canvas(obj, palette=None)

Wrap a backend object into a whitecanvas Canvas.

import matplotlib.pyplot as plt canvas = wrap_canvas(plt.gca())

Source code in whitecanvas\core.py 
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
def wrap_canvas(obj: Any, palette=None) -> Canvas:
    """
    Wrap a backend object into a whitecanvas Canvas.

    >>> import matplotlib.pyplot as plt
    >>> canvas = wrap_canvas(plt.gca())
    """
    typ = type(obj).__name__

    if _is_in_module(typ, "matplotlib", "Axes"):
        from matplotlib.axes import Axes

        from whitecanvas.backend.matplotlib import Canvas as BackendCanvas

        if not isinstance(obj, Axes):
            raise TypeError(f"Expected matplotlib Axes, got {typ}")
        backend = "matplotlib"

    elif _is_in_module(typ, "plotly", "Figure"):
        from plotly.graph_objs import Figure

        from whitecanvas.backend.plotly import Canvas as BackendCanvas

        if not isinstance(obj, Figure):
            raise TypeError(f"Expected plotly Figure, got {typ}")
        backend = "plotly"
    elif _is_in_module(typ, "bokeh", "figure"):
        from bokeh.plotting import figure

        from whitecanvas.backend.bokeh import Canvas as BackendCanvas

        if not isinstance(obj, figure):
            raise TypeError(f"Expected bokeh figure, got {typ}")
        backend = "bokeh"
    elif _is_in_module(typ, "vispy", "ViewBox"):
        from vispy.scene import ViewBox

        from whitecanvas.backend.vispy import Canvas as BackendCanvas

        if not isinstance(obj, ViewBox):
            raise TypeError(f"Expected vispy ViewBox, got {typ}")
        backend = "vispy"
    elif _is_in_module(typ, "pyqtgraph", "PlotItem"):
        from pyqtgraph import PlotItem

        from whitecanvas.backend.pyqtgraph import Canvas as BackendCanvas

        if not isinstance(obj, PlotItem):
            raise TypeError(f"Expected pyqtgraph PlotItem, got {typ}")
        backend = "pyqtgraph"
    else:
        raise TypeError(f"Cannot convert {typ} to Canvas")
    return Canvas.from_backend(BackendCanvas(obj), palette=palette, backend=backend)