Display styling

The default displaying style may not yield by default the visual representation the user wants. For these cases, the library includes a variety of styling options that can be applied at multiple levels in the user’s code.

Hierarchy of arguments

The styling options can be set at the library level, for an individual object directly or via a Collection and as an explicity argument in the display function. These settings, are ordered from lowest to highest precedence as follows:

  • library defaults

  • individual object style or at Collection level

  • in the display function


import magpylib as magpy
import plotly.graph_objects as go

from magpylib._src.style import Dipole


cuboid = magpy.magnet.Cuboid(
    magnetization=(1, 0, 0), dimension=(1, 1, 1), position=(0, 0, 0)
cylinder = magpy.magnet.Cylinder(
    magnetization=(0, 1, 0), dimension=(1, 1), position=(2, 0, 0)
sphere = magpy.magnet.Sphere(magnetization=(0, 1, 1), diameter=1, position=(4, 0, 0))
col = magpy.Collection(cuboid, cylinder, sphere)

Setting library defaults

Base defaults structure

Display styles can be set at the library default level at magpy.defaults.display.style. The default styles are separated into the following object families:

  • base : common properties for all families

  • magnet: Cuboid, Cylinder, Sphere, CylinderSegment

  • current: Line, Loop

  • sensor: Sensor

  • markers: display markers

Changing defaulfts and Magic underscore notation

Nested properties can be set with directly by accessing style attributes with the dot notation, or by assigning a dictionary with equivalent keys.

by defining the magnet_style variable as:

magnet_style = magpy.defaults.display.style.magnet

the following examples are equivalent

magnet_style.magnetization.show = True
magnet_style.magnetization.color.middle = "grey"
magnet_style.magnetization.color.mode = "tricolor"


magnet_style = {
    "magnetization": {"show": True, "color": {"middle": "grey", "mode": "tricolor"}}

To make it easier to work with nested properties, style constructors and object style method support magic underscore notation. This allows you to reference nested properties by joining together multiple nested property names with underscores.This feature mainly helps reduce the code verbosity and is heavily inspired by the plotly implementation (see plotly underscore notation). The previous examples can also be written as:

magnet_style = {
    "magnetization_show": True,
    "magnetization_color_middle": "grey",
    "magnetization_color_mode": "tricolor",

Additionally, instead of overriding the whole style constructor, style properties can be updated. The underscore notation is also supported here:


Practical example

my_default_magnetization_style = {
    "show": True,
    "color": {
        "transition": 1,
        "mode": "tricolor",
        "middle": "white",
        "north": "magenta",
        "south": "turquoise",
magpy.defaults.display.style.magnet.magnetization = my_default_magnetization_style

magpy.display(col, backend="plotly")