The Layer Classes
Retina provides Layer2D
and Layer3D
classes designed to encapsulate related plot elements
such that they may be manipulated, styled, and modified in tandem. This facility is provided
for plots created for viewing in any of the following environments:
- The native Matplotlib interface.
- The IPython or Jupyter notebooks.
- The browser via the Plotly.py and Plotly.js libraries.
The documentation provided herein is for the Matplotlib extension, while details about the Plotly implementation can be found in the "web" section of this site.
The Layer2D
Class
The Layer2D
class defines an object that holds Matplotlib artists in 2D plots.
Class-Level Properties
default_style
: Defines the template default style and applies to all Layer2D
classes
initialized downstream. Defaults to b-
, i.e. solid blue lines.
Class-Level Functions
set_default_style(cls, style)
Sets the default style for a layer by modifying the Layer2D.default_style
class property
discussed above. Changes to the Layer2D
class' default style should be instituted by a call
to this function rather than by directly modifying the class default_style
property.
Instance-Level Properties
default_attrs
: A dictionary holding the default attributes tracked by a layer. At the time of writing,
these include:
'visible'
: A boolean specifying whether or not the layer is currently visible.style
: The layer's current style. Is initialized to theLayer2D
default style.lines
: The lines contained in the layer.hlines
: The horizontal lines contained in the layer.vlines
: The vertical lines contained in the layer.x_data
: The x-coordinates of all data points contained in the layer.y_data
: The y-coordinates of all data points contained in the layer.plots
: The Matplotlib artist instances contained in the layer.patches
: The Matplotlib patch (shape) instances contained in the layer.bounds
: The Matplotlib patches (rectangles or circles) that are created when theLayer2D.bound()
function is invoked.
name
: The string used to identify the layer. Provided by the user on class instantiation.
axes
: The Matplotlib Axes instance to which the layer is attached.
Instance-Level Functions
show()
: Sets the layer's visible
property to True
and sets the visibility of each layer artist to True
.
hide()
: Sets the layer's visible
property to False
and sets the visibility of each layer artist to False
.
toggle_display()
: Toggles the visibility of the layer. In other words, if the layer.visible = False
then
layer.show()
is called. Otherwise layer.hide()
is called.
add_line(*args, **kwargs)
: Adds a Matplotlib Line2D
artist to the layer. Also appends the artist to the
layer.lines
attribute.
add_vline(self, x)
: Adds a Matplotlib vertical Line2D
artist satisfying the equation x = x
to the layer.
Also appends the artist to the layer.lines
attribute.
set_style(style)
: Applies a Matplotlib style to all artists residing in the layer by updating the layer.style
attribute. As such, the layer must be rebuilt for changes to take effect.
set_prop(*args, **kwargs)
: Sets the provided artist property(s) to the provided value(s) for all artists in the
layer via a call to Matplotlib's setp
function.
bold(linewidth=None)
: Doubles the linewidth of all artists in the layer unless a value for the linewidth argument
is specified.
unbold(linewidth=None)
: Halves the linewidth of all artists in the layer so as to undo the effects caused by the
bold()
function.
add_data(x_data, y_data)
: Add arrays of x
and y
data values to the layer.
bound(shape=Rectangle, **kwargs)
: Draws a boundary having the specified shape around the artists contained in the layer.
shape
should be a valid Matplotlib patch class.
unbound()
: Removes the bounds drawn by the bound()
function from the layer.
add_attrs()
: Add a custom attribute to the layer class.
clear()
: Clears the layer, setting all attributes to either None
or their default values as specified in default_attrs
.
The Layer3D
Class
The Layer3D
class inherits from the Layer2D
classes and implements all of the functions defined therein with the exception
of add_line()
, add_vline()
, and add_hline()
.
Instance-Level Properties
visible
: DefaultTrue
style
:Layer3D.default_style
lines
hlines
vlines
x_data
y_data
z_data
: The z-coordinates of the data contained in the layer.plots
planes
: The list of planes contained in the layer.patches
bounds
add_data(x_data, y_data, z_data)
: Add data to the layer specified by its x, y, and z coordinates.
add_plane(point, normal, **kwargs)
: Add a plane to the layer defined by the following format.
normal -- Normal vector (a, b, c) to the plane. point -- point (x, y, z) on the plane
Adds a plane having the equation ax + by + cz = d.
bound(shape='cube', color='b', **kwargs)
: Draws a cube having the provided color around the boundary of the artists in the layer.
unbound()
: Undoes the 3D bounding method.