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#

Provides the 3D-model parameters for an arrow in dictionary form, based on number of vertices of the base, diameter and height. The zero position is in the barycenter of the vertices.

Parameters

  • backend (str) – Plotting backend corresponding to the trace. Can be one of [‘generic’, ‘matplotlib’, ‘plotly’].

  • base (int, default=30) – Number of vertices of the arrow base.

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

  • height (int, default=1) – Arrow height.

  • pivot (str, default='middle') – The part of the arrow that is anchored to the grid and about which it rotates. Can be one of [‘tail’, ‘middle’, ‘tip’].

  • position (array_like, shape (3,), default=(0,0,0)) – Reference position of the vertices in the global CS. The zero position is in the barycenter of the vertices.

  • orientation (scipy Rotation object with length 1 or m, default=`identity`) – Orientation of the vertices in the global CS.

  • show (bool, default=True) – Shows/hides model3d object based on provided trace.

  • scale (float, default=1) – Scaling factor by which the trace vertices coordinates are multiplied.

  • **kwargs (dict, optional) – Additional keyword arguments to be passed to the trace constructor directly. (e.g. opacity=0.5 for plotly or alpha=0.5 for matplotlib)

Returns

3D-model – A dictionary with necessary key/value pairs with the necessary information to construct a 3D-model.

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#

Provides the 3D-model parameters for a cuboid in dictionary form, based on the given dimension. The zero position is in the barycenter of the vertices.

Parameters

  • backend (str) – Plotting backend corresponding to the trace. Can be one of [‘generic’, ‘matplotlib’, ‘plotly’].

  • dimension (3-tuple, default=(1,1,1)) – Length of the cuboid sides x,y,z.

  • position (array_like, shape (3,), default=(0,0,0)) – Reference position of the vertices in the global CS. The zero position is in the barycenter of the vertices.

  • orientation (scipy Rotation object with length 1 or m, default=`identity`) – Orientation of the vertices in the global CS.

  • show (bool, default=True) – Shows/hides model3d object based on provided trace.

  • scale (float, default=1) – Scaling factor by which the trace vertices coordinates are multiplied.

  • **kwargs (dict, optional) – Additional keyword arguments to be passed to the trace constructor directly. (e.g. opacity=0.5 for plotly or alpha=0.5 for matplotlib)

Returns

3D-model – A dictionary with necessary key/value pairs with the necessary information to construct a 3D-model.

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#

Provides the 3D-model parameters for a cylinder segment in dictionary form, based on inner and outer diameters, height, and section angles in degrees. The zero position is at z=0 at the center point of the arcs.

Parameters

  • backend (str) – Plotting backend corresponding to the trace. Can be one of [‘generic’, ‘matplotlib’, ‘plotly’].

  • dimension (array_like, shape (5,), default=`None`) – Dimension/Size of the cylinder segment of the form (r1, r2, h, phi1, phi2) where r1<r2 denote inner and outer radii in units of [mm], phi1<phi2 denote the cylinder section angles in units of [deg] and h is the cylinder height in units of [mm].

  • vert (int, default=50) – Number of vertices along a the complete 360 degrees arc. The number along the phi1-phi2-arc is computed with max(5, int(vert * abs(phi1 - phi2) / 360)).

  • position (array_like, shape (3,), default=(0,0,0)) – Reference position of the vertices in the global CS. The zero position is in the barycenter of the vertices.

  • orientation (scipy Rotation object with length 1 or m, default=`identity`) – Orientation of the vertices in the global CS.

  • show (bool, default=True) – Shows/hides model3d object based on provided trace.

  • scale (float, default=1) – Scaling factor by which the trace vertices coordinates are multiplied.

  • **kwargs (dict, optional) – Additional keyword arguments to be passed to the trace constructor directly. (e.g. opacity=0.5 for plotly or alpha=0.5 for matplotlib)

Returns

3D-model – A dictionary with necessary key/value pairs with the necessary information to construct a 3D-model.

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#

Provides the 3D-model parameters for an ellipsoid in dictionary form, based on number of vertices of the circumference, and the dimension. The zero position is in the barycenter of the vertices.

Parameters

  • backend (str) – Plotting backend corresponding to the trace. Can be one of [‘generic’, ‘matplotlib’, ‘plotly’].

  • dimension (tuple, default=(1.0, 1.0, 1.0)) – Dimension in the x,y,z directions.

  • vert (int, default=15) – Number of vertices along the circumference.

  • position (array_like, shape (3,), default=(0,0,0)) – Reference position of the vertices in the global CS. The zero position is in the barycenter of the vertices.

  • orientation (scipy Rotation object with length 1 or m, default=`identity`) – Orientation of the vertices in the global CS.

  • show (bool, default=True) – Shows/hides model3d object based on provided trace.

  • scale (float, default=1) – Scaling factor by which the trace vertices coordinates are multiplied.

  • **kwargs (dict, optional) – Additional keyword arguments to be passed to the trace constructor directly. (e.g. opacity=0.5 for plotly or alpha=0.5 for matplotlib)

Returns

3D-model – A dictionary with necessary key/value pairs with the necessary information to construct a 3D-model.

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#

Provides the 3D-model parameters for a prism in dictionary form, based on number of vertices of the base, diameter and height. The zero position is in the barycenter of the vertices.

Parameters

  • backend (str) – Plotting backend corresponding to the trace. Can be one of [‘generic’, ‘matplotlib’, ‘plotly’].

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

  • diameter (float, default=1) – Diameter dimension inscribing the base.

  • height (float, default=1) – Prism height in the z-direction.

  • position (array_like, shape (3,), default=(0,0,0)) – Reference position of the vertices in the global CS. The zero position is in the barycenter of the vertices.

  • orientation (scipy Rotation object with length 1 or m, default=`identity`) – Orientation of the vertices in the global CS.

  • show (bool, default=True) – Shows/hides model3d object based on provided trace.

  • scale (float, default=1) – Scaling factor by which the trace vertices coordinates are multiplied.

  • **kwargs (dict, optional) – Additional keyword arguments to be passed to the trace constructor directly. (e.g. opacity=0.5 for plotly or alpha=0.5 for matplotlib)

Returns

3D-model – A dictionary with necessary key/value pairs with the necessary information to construct a 3D-model.

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#

Provides the 3D-model parameters for a pyramid in dictionary form, based on number of vertices of the base, diameter and height. The zero position is in the barycenter of the vertices.

Parameters

  • backend (str) – Plotting backend corresponding to the trace. Can be one of [‘generic’, ‘matplotlib’, ‘plotly’].

  • base (int, default=30) – Number of vertices of the cone base.

  • diameter (float, default=1) – Diameter of the cone base.

  • height (int, default=1) – Pyramid height.

  • pivot (str, default='middle') – The part of the cone that is anchored to the grid and about which it rotates. Can be one of [‘tail’, ‘middle’, ‘tip’].

  • position (array_like, shape (3,), default=(0,0,0)) – Reference position of the vertices in the global CS. The zero position is in the barycenter of the vertices.

  • orientation (scipy Rotation object with length 1 or m, default=`identity`) – Orientation of the vertices in the global CS.

  • show (bool, default=True) – Shows/hides model3d object based on provided trace.

  • scale (float, default=1) – Scaling factor by which the trace vertices coordinates are multiplied.

  • **kwargs (dict, optional) – Additional keyword arguments to be passed to the trace constructor directly. (e.g. opacity=0.5 for plotly or alpha=0.5 for matplotlib)

Returns

3D-model – A dictionary with necessary key/value pairs with the necessary information to construct a 3D-model.

Return type

dict

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

Provides the 3D-model parameters for a pyramid in dictionary form, based on number of vertices of the base, diameter and height. The zero position is in the barycenter of the vertices.

Parameters

  • backend (str) – Plotting backend corresponding to the trace. Can be one of [‘matplotlib’, ‘plotly’].

  • vertices (ndarray, shape (4,3)) – Vertices (x1,y1,z1), (x2,y2,z2), (x3,y3,z3), (x4,y4,z4), in the relative coordinate system of the tetrahedron.

  • position (array_like, shape (3,), default=(0,0,0)) – Reference position of the vertices in the global CS. The zero position is in the barycenter of the vertices.

  • orientation (scipy Rotation object with length 1 or m, default=`identity`) – Orientation of the vertices in the global CS.

  • show (bool, default=True) – Shows/hides model3d object based on provided trace.

  • scale (float, default=1) – Scaling factor by which the trace vertices coordinates are multiplied.

  • **kwargs (dict, optional) – Additional keyword arguments to be passed to the trace constructor directly. (e.g. opacity=0.5 for plotly or alpha=0.5 for matplotlib)

Returns

3D-model – A dictionary with necessary key/value pairs with the necessary information to construct a 3D-model.

Return type

dict

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

Provides the 3D-model parameters for a custom triangular mesh in dictionary form, based on number of vertices of the base, diameter and height. The zero position is in the barycenter of the vertices.

Parameters

  • backend (str) – Plotting backend corresponding to the trace. Can be one of [‘matplotlib’, ‘plotly’].

  • vertices (ndarray, shape (4,3)) – Vertices (x1,y1,z1), (x2,y2,z2), (x3,y3,z3), (x4,y4,z4), in the relative coordinate system of the triangular mesh.

  • triangles (ndarray, shape (4,3)) – For each triangle, the indices of the three points that make up the triangle, ordered in an anticlockwise manner. If not specified, a scipy.spatial.ConvexHull triangulation is calculated.

  • position (array_like, shape (3,), default=(0,0,0)) – Reference position of the vertices in the global CS. The zero position is in the barycenter of the vertices.

  • orientation (scipy Rotation object with length 1 or m, default=`identity`) – Orientation of the vertices in the global CS.

  • show (bool, default=True) – Shows/hides model3d object based on provided trace.

  • scale (float, default=1) – Scaling factor by which the trace vertices coordinates are multiplied.

  • **kwargs (dict, optional) – Additional keyword arguments to be passed to the trace constructor directly. (e.g. opacity=0.5 for plotly or alpha=0.5 for matplotlib)

Returns

3D-model – A dictionary with necessary key/value pairs with the necessary information to construct a 3D-model.

Return type

dict