magpylib · Alexboiboi · May 31, 2024 · Jun 1, 2024 · Jun 3, 2024 · Jun 3, 2024
diff --git a/.binder/apt.txt b/.binder/apt.txt
diff --git a/.binder/labconfig/default_setting_overrides.json b/.binder/labconfig/default_setting_overrides.json
diff --git a/.binder/postBuild b/.binder/postBuild
diff --git a/.binder/requirements.txt b/.binder/requirements.txt
diff --git a/.gitignore b/.gitignore
@@ -158,6 +158,7 @@ Thumbs.db
 *~
 *.swp
 __temp*.py
+__temp*.ipynb
 
 # uv
 uv.lock

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -40,7 +40,9 @@ repos:
       - id: prettier
         types_or: [yaml, markdown, html, css, scss, javascript, json]
         args: [--prose-wrap=always]
-        exclude: ^docs/ # messes up colon fences for grids in docs
+        # Exclude docs (messes up colon fences for grids)
+        # Excclude test YAML files from formatting (messes up fig data diffs)
+        exclude: ^docs/|^tests/.*\.ya?ml$
 
   - repo: https://github.com/astral-sh/ruff-pre-commit
     rev: "v0.13.0"

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 ## [Unreleased] - YYYY-MM-DD
 
+- Added new `style.pixel.field` parameters to quickly represent vector fields
+  ([#793](https://github.com/magpylib/magpylib/pull/793))
 - Added the `current_sheet_Hfield` core computation function, and the classes
   `TriangleStrip` and `TriangleSheet` enabling current sheets in the object
   oriented interface. ([#788](https://github.com/magpylib/magpylib/issues/788))

diff --git a/docs/_pages/user_guide/docs/docs_styles.md b/docs/_pages/user_guide/docs/docs_styles.md
@@ -13,6 +13,7 @@ orphan: true
 ---
 
 (guide-graphic-styles)=
+
 # Graphic styles
 
 The graphic styles define how Magpylib objects are displayed visually when calling `show`. They can be fine-tuned and individualized to suit requirements and taste.
@@ -26,6 +27,7 @@ Graphic styles can be defined in various ways:
 The following sections describe these styling options and how to customize them.
 
 (guide-graphic-styles-default)=
+
 ## Default style
 
 The default style is stored in `magpylib.defaults.display.style`. Note that the installation default styles differ slightly between different [graphic backends](guide-graphic-backends) depending on their respective capabilities. Specifically, the magnet magnetization in Matplotlib is displayed with arrows by default, while it is displayed using a color scheme in Plotly and Pyvista. The color scheme is also implemented in Matplotlib, but it is visually unsatisfactory.
@@ -109,7 +111,6 @@ The default Magpylib style abides by the tri-color scheme for ideal-typical magn
 
 A list of all style options can be found [here](examples-list-of-styles).
 
-
 ## Magic underscore notation
 
 To facilitate working with deeply nested properties, all style constructors and object style methods support the "magic underscore notation". It enables referencing nested properties by joining together multiple property names with underscores. This feature mainly helps reduce the code verbosity and is heavily inspired by the [Plotly underscore notation](https://plotly.com/python/creating-and-updating-figures/#magic-underscore-notation)).
@@ -246,6 +247,7 @@ magpy.defaults.display.style.as_dict(flatten=True, separator=".")
 ```
 
 (examples-own-3d-models)=
+
 ## Custom 3D models
 
 Each Magpylib object has a default 3D representation that is displayed with `show`. It is possible to disable the default model and to provide Magpylib with a custom model.
@@ -471,6 +473,7 @@ obj0.show(obj1, obj2, obj3, obj4, obj5, backend="plotly")
 ```
 
 ((guide-docs-style-cad))=
+
 ## Adding a CAD model
 
 The following code sample shows how a standard CAD model (*.stl file) can be transformed into a Magpylib `Trace3d` object.
@@ -561,3 +564,100 @@ magpy.show(args, **kwargs, backend="plotly")
 ```{code-cell} ipython3
 
 ```
+
+(styles-pixel-vectorfield)=
+
+## Pixel Field
+
+:::{versionadded} 5.2
+Pixel Vector Field
+:::
+
+The `pixel` of a `Sensor` object can be visualized as arrows representing the values of the vector fields B, H, J, or M. This allows for quick and intuitive inspection of the field distributions.
+
+### Parameters (`style.pixel.field`)
+
+- **`source`** *(default=`None`)*:
+  Defines the field source of the vector field representation.
+  - `None`: No field representation is shown
+  - `"B"`, `"Hxy"`, `"Jxyz"`, etc.: Colors are mapped to the magnitude of the specified field.
+
+- **`symbol`** *(default=`"cone"`)*:
+  Specifies the rendering symbol for field values.
+  - `"none"`: `pixel.symbol` representation takes precedence of `pixel.field.symbol`.
+  - `"cone"`: 3D cone representation.
+  - `"arrow3d"`: 3D arrow representation.
+  - `"arrow"`: 2D line-based arrow.
+
+- **`shownull`** *(default=`True`)*:
+  Toggles the visibility of pixel with zero and invalid field vectors.
+  - `True`: Null vectors are displayed.
+  - `False`: Null vectors are hidden.
+
+- **`sizescaling`** *(default=`"uniform"`)*:
+    Determines how arrow size relates to the `source` magnitude.
+  - `"uniform"`: Uniform arrow size.
+  - `"linear"`: Size proportional to magnitude.
+  - `"log"`: Size proportional to the normalized logarithm of the magnitude.
+  - `"log^n"`: Size proportional to the normalized nth (2 to 9) logarithm of the magnitude.
+
+- **`sizemin`** *(default=`0.1`)*
+    Minimum relative size of field symbols. A float between 0 and 1.
+    When displaying field vectors this controls how small the symbols
+    can become relative to their maximum size. A value of 0 allows symbols to shrink to zero size,
+    while 0.5 ensures symbols are at least 50% of their maximum size.
+
+- **`colorscaling`** *(default=`"uniform"`)*:
+    Determines how arrow color relates to the `source` magnitude.
+  - `"uniform"`: Uniform color for all arrows.
+  - `"linear"`: Color scaling proportional to magnitude.
+  - `"log"`: Color scaling proportional to the normalized logarithm of the magnitude.
+  - `"log^n"`: Color scaling proportional to the normalized nth (2 to 9) logarithm of the magnitude.
+
+- **`colormap`** *(default=`"Viridis"`)*:
+  Specifies the colormap used for color mapping. Supports standard color maps (e.g., `"Viridis"`, `"Inferno"`, `"Magma"`, etc.) compatible with both Plotly and Matplotlib.
+
+```{note}
+- Pixels with zero or invalid field values are rendered using the default representation (`point`/`box` or according to `style.pixel.symbol`).
+- Magnitude normalization is performed individually for each sensor along its path.
+- `style.pixel.size` controls also the arrow size.
+```
+
+### Pixel Field Minimal Example
+
+The following example demonstrates how to visualize the `Sensor` pixel array as a vector field using the `style.pixel.field` settings.
+
+```{code-cell} ipython3
+:tags: [hide-input]
+
+import numpy as np
+import magpylib as magpy
+
+# Define a cuboid magnet
+cube = magpy.magnet.Cuboid(
+    polarization=(0, 0, 1),
+    dimension=(1, 1, 1),
+)
+
+# Create a 2D grid of pixel positions in the xy-plane
+xy_grid = np.mgrid[-2:2:15j, -2:2:15j, 0:0:1j].T[0]
+
+# Define pixel field style
+pixel_style = {
+    "source" : "B",
+    "symbol"       : "arrow3d",
+    "sizemode"     : "uniform",
+    "shownull"     : True,
+    "colormap"   : "Magma"
+}
+
+# Create sensor with pixel array and applied style
+sens = magpy.Sensor(
+    pixel=xy_grid,
+    position=(0,0,2),
+    style_pixel_field=pixel_style,
+)
+
+# Display the sensor and magnet using the Plotly backend
+magpy.show([sens, cube], backend='plotly')
+```
diff --git a/docs/_pages/user_guide/examples/examples_index.md b/docs/_pages/user_guide/examples/examples_index.md
@@ -94,6 +94,14 @@
 :img-bottom: ../../../_static/images/examples_icon_vis_pv_streamlines.png
 :::
 
+:::{grid-item-card} {ref}`examples-vis-vectorfield`
+:text-align: center
+:link: examples-vis-vectorfield
+:link-type: ref
+:link-alt: link to example
+:img-bottom: ../../../_static/images/examples_icon_vis_vectorfield.png
+:::
+
 
 
 ::::
@@ -296,6 +304,7 @@ examples_vis_animations.md
 examples_vis_subplots.md
 examples_vis_mpl_streamplot.md
 examples_vis_pv_streamlines.md
+examples_vis_vectorfield.md
 
 examples_shapes_superpos.md
 examples_shapes_convex_hull.md

diff --git a/docs/_pages/user_guide/examples/examples_vis_vectorfield.md b/docs/_pages/user_guide/examples/examples_vis_vectorfield.md
@@ -0,0 +1,162 @@
+---
+jupytext:
+  formats: md:myst
+  text_representation:
+    extension: .md
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.17.1
+kernelspec:
+  name: python3
+  display_name: Python 3 (ipykernel)
+  language: python
+---
+
+(examples-vis-vectorfield)=
+
+# Pixel Field (Quiver Plot)
+
+:::{versionadded} 5.2
+Pixel Vector Field
+:::
+
+The `Sensor` object with its `pixel` attribute can be conveniently used to visualize vector fields `"B"`, `"H"`, `"M"`, or `"J"` as quiver plots. Detailed documentation is available in the [styles-pixel-vectorfield](styles-pixel-vectorfield) section. This notebook provides practical examples and explanations of relevant parameters for effective usage.
+
+## Example 1: Transparent Magnet
+
+A simple example using pixel field functionality, combined with magnet transparency, displays the B field on a surface passing through the magnet.
+
+```{code-cell} ipython3
+:tags: [hide-input]
+
+import numpy as np
+import magpylib as magpy
+
+# Define a magnet with opacity
+magnet = magpy.magnet.Cuboid(
+    polarization=(1, 1, 0),
+    dimension=(4e-3, 4e-3, 2e-3),
+    style_opacity=0.5,
+)
+
+# Create a grid of pixel positions in the xy-plane
+xy_grid = np.mgrid[-4e-3:4e-3:15j, -4e-3:4e-3:15j, 0:0:1j].T[0]
+
+# Create a sensor with pixel array and pixel field style
+sens = magpy.Sensor(
+    pixel=xy_grid,
+    style_pixel_field_source="B",
+    style_pixel_field_sizescaling="log",
+)
+
+# Display the sensor and magnet using the Plotly backend
+magpy.show([sens, magnet], backend="plotly")
+```
+
+## Example 2: Complex Pixel Grids
+
+Sensor pixels are not restricted to any specific grid structure and can be positioned freely to represent curved surfaces, lines, or individual points of interest.
+
+The following example demonstrates visualization of the magnetic field of a magnetic pole wheel, evaluated along curved surfaces and lines, using different color maps and arrow shapes.
+
+```{code-cell} ipython3
+:tags: [hide-input]
+
+from numpy import pi, sin, cos, linspace
+import magpylib as magpy
+
+# Create a pole wheel magnet composed of 12 alternating cylinder segments
+pole_wheel = magpy.Collection()
+for i in range(12):
+    zone = magpy.magnet.CylinderSegment(
+        dimension=(1.8, 2, 1, -15, 15),
+        polarization=((-1)**i, 0, 0),
+    ).rotate_from_angax(30*i, axis="z")
+    pole_wheel.add(zone)
+
+# Sensor 1: Pixel line along a circle in the xz-plane
+ang1 = linspace(0, 2*pi, endpoint=False)
+pixel_line = [(cos(a), 0, sin(a)) for a in ang1]
+
+sensor1 = magpy.Sensor(
+    pixel=pixel_line,
+    style_pixel_field_source="H",
+)
+
+# Sensor 2: Curved surface (vertical cylinder segment)
+z_values = linspace(-1, 1, 10)
+ang2 = linspace(-9*pi/8, -2*pi/8, 30)
+pixel_grid2 = [[(3.5*cos(a), 3.5*sin(a), z) for a in ang2] for z in z_values]
+
+sensor2 = magpy.Sensor(
+    pixel=pixel_grid2,
+    style_pixel_field={
+        "source": "H",
+        "sizescaling": "uniform",
+        "colorscale": "Blues",
+        "symbol": "arrow3d",
+    }
+)
+
+# Sensor 3: Curved surface (horizontal annular sector)
+r_values = linspace(3, 4, 5)
+ang3 = linspace(-pi/8, 6*pi/8, 30)
+pixel_grid3 = [[(r*cos(a), r*sin(a), 0) for a in ang3] for r in r_values]
+
+sensor3 = magpy.Sensor(
+    pixel=pixel_grid3,
+    style_pixel_field={
+        "source": "H",
+        "sizescaling": "log",
+        "colorscale": "Plasma",
+        "symbol": "arrow3d",
+    }
+)
+
+# Display sensors and magnets using Plotly backend
+magpy.show(
+    [sensor1, sensor2, sensor3, pole_wheel],
+    backend="plotly",
+    style_arrows_x_show=False,
+    style_arrows_y_show=False,
+    style_arrows_z_show=False,
+)
+```
+
+## Example 3: Pixel Field Animation
+
+Pixel fields can be combined with animation to create spectacular visualizations, such as displaying the magnetic field of rotating magnets.
+
+```{code-cell} ipython3
+:tags: [hide-input]
+
+import numpy as np
+import magpylib as magpy
+
+# Create a cuboid magnet with vertical polarization
+magnet = magpy.magnet.Cuboid(
+    polarization=(0, 0, 1),
+    dimension=(1, 3, 1)
+)
+
+# Apply a rotation to the Cuboid that generates a path with 51 steps
+magnet.rotate_from_angax(
+    angle=np.linspace(0, 360, 51),
+    axis="y",
+    start=0
+)
+
+# Create a sensor with pixel grid in the xy-plane at z=1
+pixel_grid = np.mgrid[-2:2:12j, -2:2:12j, 1:1:1j].T[0]
+sensor = magpy.Sensor(pixel=pixel_grid)
+
+# Display as animation in the Plotly backend
+magpy.show(
+    magnet,
+    sensor,
+    animation=True,
+    style_pixel_field_symbol="arrow3d",
+    style_pixel_field_source="B",
+    backend="plotly",
+)
+```
diff --git a/docs/_pages/user_guide/guide_index.md b/docs/_pages/user_guide/guide_index.md
@@ -23,7 +23,7 @@ docs/docs_magpylib_force.md
 ```
 
 ```{toctree}
-:maxdepth: 2
+:maxdepth: 1
 :caption: Resources
 guide_resources_01_physics.md
 examples/examples_index.md

diff --git a/docs/_static/images/examples_icon_vis_vectorfield.png b/docs/_static/images/examples_icon_vis_vectorfield.png
-Original file line number
+Diff line change
@@ Expand Up / @@ -158,6 +158,7 @@ Thumbs.db @@
     *~
     *.swp
     __temp*.py
+    __temp*.ipynb
     # uv
     uv.lock
@@ Expand Down @@