magpylib.graphics.model3d package#

The magpylib.display.plotly sub-package provides useful functions for convenient creation of 3D traces for commonly used objects in the library.

magpylib.graphics.model3d.make_Arrow(backend='generic', base=3, diameter=0.3, height=1, pivot='middle', position=None, orientation=None, show=True, scale=1, **kwargs) → dict#

Return a model3d dictionary for an arrow (prism shaft + pyramid head).

Parameters:

  • backend ({'generic', 'matplotlib', 'plotly'}, default 'generic') – Plotting backend.

  • base (int, default 3) – Number of vertices of the regular polygon bases.

  • diameter (float, default 0.3) – Diameter of the arrow base.

  • height (float, default 1.0) – Arrow height.

  • pivot ({'tail', 'middle', 'tip'}, default 'middle') – Anchor point about which the arrow rotates.

  • position (array-like, shape (3,), default None) – Reference position of the vertices in the global CS. The zero position is in the centroid of the vertices. If None, uses (0, 0, 0).

  • orientation (scipy.spatial.transform.Rotation | None, default None) – Orientation to apply in the global CS.

  • show (bool, default True) – Show or hide the resulting model3d object.

  • scale (float, default 1) – Factor by which the vertex coordinates are multiplied.

  • **kwargs (dict) – Additional constructor kwargs passed to the backend trace (e.g., opacity=0.5 for Plotly or alpha=0.5 for Matplotlib).

Returns:

Backend-agnostic model3d specification for rendering.

Return type:

dict

magpylib.graphics.model3d.make_Cuboid(backend='generic', dimension=(1.0, 1.0, 1.0), position=None, orientation=None, show=True, scale=1, **kwargs) → dict#

Return a model3d dictionary for a cuboid.

Parameters:

  • backend ({'generic', 'matplotlib', 'plotly'}, default 'generic') – Plotting backend.

  • dimension (tuple[float, float, float], default (1.0, 1.0, 1.0)) – Side lengths along the x, y, and z axes.

  • position (array-like, shape (3,), default None) – Reference position of the vertices in the global CS. The zero position is in the centroid of the vertices. If None, uses (0, 0, 0).

  • orientation (scipy.spatial.transform.Rotation | None, default None) – Orientation to apply in the global CS.

  • show (bool, default True) – Show or hide the resulting model3d object.

  • scale (float, default 1) – Factor by which the vertex coordinates are multiplied.

  • **kwargs (dict) – Additional constructor kwargs passed to the backend trace (e.g., opacity=0.5 for Plotly or alpha=0.5 for Matplotlib).

Returns:

Backend-agnostic model3d specification for rendering.

Return type:

dict

magpylib.graphics.model3d.make_CylinderSegment(backend='generic', dimension=(1.0, 2.0, 1.0, 0.0, 90.0), vert=50, position=None, orientation=None, show=True, scale=1, **kwargs) → dict#

Return a model3d dictionary for a hollow cylinder segment.

Parameters:

  • backend ({'generic', 'matplotlib', 'plotly'}, default 'generic') – Plotting backend.

  • dimension (tuple[float, float, float, float, float], default (1.0, 2.0, 1.0, 0.0, 90.0)) – Cylinder parameters (r1, r2, h, phi1, phi2), where r1 < r2 are inner and outer radii, h is height, and phi1 < phi2 are section angles in degrees. The zero reference is at z=0 at the arc center point.

  • vert (int, default 50) – Sampling density along a full 360° arc. Along [phi1, phi2] it uses max(5, int(vert * abs(phi2 - phi1) / 360)).

  • position (array-like, shape (3,), default None) – Reference position of the vertices in the global CS. The zero position is in the centroid of the vertices. If None, uses (0, 0, 0).

  • orientation (scipy.spatial.transform.Rotation | None, default None) – Orientation to apply in the global CS.

  • show (bool, default True) – Show or hide the resulting model3d object.

  • scale (float, default 1) – Factor by which the vertex coordinates are multiplied.

  • **kwargs (dict) – Additional constructor kwargs passed to the backend trace (e.g., opacity=0.5 for Plotly or alpha=0.5 for Matplotlib).

Returns:

Backend-agnostic model3d specification for rendering.

Return type:

dict

magpylib.graphics.model3d.make_Ellipsoid(backend='generic', dimension=(1.0, 1.0, 1.0), vert=15, position=None, orientation=None, show=True, scale=1, **kwargs) → dict#

Return a model3d dictionary for an ellipsoid.

Parameters:

  • backend ({'generic', 'matplotlib', 'plotly'}, default 'generic') – Plotting backend.

  • dimension (tuple[float, float, float], default (1.0, 1.0, 1.0)) – Principal axes lengths along x, y, and z.

  • vert (int, default 15) – Sampling density used to approximate the surface.

  • position (array-like, shape (3,), default None) – Reference position of the vertices in the global CS. The zero position is in the centroid of the vertices. If None, uses (0.0, 0.0, 0.0).

  • orientation (scipy.spatial.transform.Rotation | None, default None) – Orientation to apply in the global CS.

  • show (bool, default True) – Show or hide the resulting model3d object.

  • scale (float, default 1) – Factor by which the vertex coordinates are multiplied.

  • **kwargs (dict) – Additional constructor kwargs passed to the backend trace (e.g., opacity=0.5 for Plotly or alpha=0.5 for Matplotlib).

Returns:

Backend-agnostic model3d specification for rendering.

Return type:

dict

magpylib.graphics.model3d.make_Prism(backend='generic', base=3, diameter=1.0, height=1.0, position=None, orientation=None, show=True, scale=1, **kwargs) → dict#

Return a model3d dictionary for a right prism with a regular polygon base.

Parameters:

  • backend ({'generic', 'matplotlib', 'plotly'}, default 'generic') – Plotting backend.

  • base (int, default 3) – Number of vertices of the base polygon in the xy-plane.

  • diameter (float, default 1.0) – Diameter of the circumscribed circle of the base polygon.

  • height (float, default 1.0) – Prism height along the z-direction.

  • position (array-like, shape (3,), default None) – Reference position of the vertices in the global CS. The zero position is in the centroid of the vertices. If None, uses (0, 0, 0).

  • orientation (scipy.spatial.transform.Rotation | None, default None) – Orientation to apply in the global CS.

  • show (bool, default True) – Show or hide the resulting model3d object.

  • scale (float, default 1) – Factor by which the vertex coordinates are multiplied.

  • **kwargs (dict) – Additional constructor kwargs passed to the backend trace (e.g., opacity=0.5 for Plotly or alpha=0.5 for Matplotlib).

Returns:

Backend-agnostic model3d specification for rendering.

Return type:

dict

magpylib.graphics.model3d.make_Pyramid(backend='generic', base=3, diameter=1, height=1, pivot='middle', position=None, orientation=None, show=True, scale=1, **kwargs) → dict#

Return a model3d dictionary for a pyramid with a regular polygon base.

Parameters:

  • backend ({'generic', 'matplotlib', 'plotly'}, default 'generic') – Plotting backend.

  • base (int, default 3) – Number of vertices of the base polygon.

  • diameter (float, default 1.0) – Diameter of the circumscribed circle of the base polygon.

  • height (float, default 1.0) – Pyramid height.

  • pivot ({'tail', 'middle', 'tip'}, default 'middle') – Anchor point about which the pyramid rotates.

  • position (array-like, shape (3,), default None) – Reference position of the vertices in the global CS. The zero position is in the centroid of the vertices. If None, uses (0, 0, 0).

  • orientation (scipy.spatial.transform.Rotation | None, default None) – Orientation to apply in the global CS.

  • show (bool, default True) – Show or hide the resulting model3d object.

  • scale (float, default 1) – Factor by which the vertex coordinates are multiplied.

  • **kwargs (dict) – Additional constructor kwargs passed to the backend trace (e.g., opacity=0.5 for Plotly or alpha=0.5 for Matplotlib).

Returns:

Backend-agnostic model3d specification for rendering.

Return type:

dict

magpylib.graphics.model3d.make_Tetrahedron(backend='generic', vertices=None, position=None, orientation=None, show=True, scale=1, **kwargs) → dict#

Return a model3d dictionary for a tetrahedron.

Parameters:

  • backend ({'generic', 'matplotlib', 'plotly'}, default 'generic') – Plotting backend.

  • vertices (array-like, shape (4, 3)) – Vertex coordinates (x1, y1, z1), …, (x4, y4, z4) in the tetrahedron’s local coordinate system.

  • position (array-like, shape (3,), default None) – Reference position of the vertices in the global CS. The zero position is in the centroid of the vertices. If None, uses (0, 0, 0).

  • orientation (scipy.spatial.transform.Rotation | None, default None) – Orientation to apply in the global CS.

  • show (bool, default True) – Show or hide the resulting model3d object.

  • scale (float, default 1) – Factor by which the vertex coordinates are multiplied.

  • **kwargs (dict) – Additional constructor kwargs passed to the backend trace (e.g., opacity=0.5 for Plotly or alpha=0.5 for Matplotlib).

Returns:

Backend-agnostic model3d specification for rendering.

Return type:

dict

magpylib.graphics.model3d.make_TriangularMesh(backend='generic', vertices=None, faces=None, position=None, orientation=None, show=True, scale=1, **kwargs) → dict#

Return a model3d dictionary for a custom triangular mesh.

Parameters:

  • backend ({'generic', 'matplotlib', 'plotly'}, default 'generic') – Plotting backend.

  • vertices (array-like, shape (n, 3)) – Vertex coordinates in the local coordinate system of the mesh.

  • faces (array-like, shape (m, 3), default None) – For each triangle, the indices of its three vertices in anticlockwise order. If None, a scipy.spatial.ConvexHull triangulation is used.

  • position (array-like, shape (3,), default None) – Reference position of the vertices in the global CS. The zero position is in the centroid of the vertices. If None, uses (0, 0, 0).

  • orientation (scipy.spatial.transform.Rotation | None, default None) – Orientation to apply in the global CS.

  • show (bool, default True) – Show or hide the resulting model3d object.

  • scale (float, default 1) – Factor by which the vertex coordinates are multiplied.

  • **kwargs (dict) – Additional constructor kwargs passed to the backend trace (e.g., opacity=0.5 for Plotly or alpha=0.5 for Matplotlib).

Returns:

Backend-agnostic model3d specification for rendering.

Return type:

dict