add_scatter

Subplot.add_scatter(data, colors='w', cmap=None, cmap_transform=None, color_mode='auto', mode='markers', markers='o', uniform_marker=True, custom_sdf=None, edge_colors='black', uniform_edge_color=True, edge_width=1.0, image=None, point_rotations=0, point_rotation_mode='uniform', sizes=1, uniform_size=True, size_space='screen', **kwargs)

Create a Scatter Graphic, 2d or 3d

Parameters:

• data (array-like) – Scatter data to plot, Can provide 2D, or a 3D data. 2D data must be of shape [n_points, 2]. 3D data must be of shape [n_points, 3]

• colors (str, array, tuple, list, Sequence, default "w") – specify colors as a single human-readable string, a single RGBA array, or a Sequence (array, tuple, or list) of strings or RGBA arrays

• cmap (str, optional) – apply a colormap to the scatter instead of assigning colors manually, this overrides any argument passed to “colors”. For supported colormaps see the cmap library catalogue: https://cmap-docs.readthedocs.io/en/stable/catalog/

• cmap_transform (1D array-like or list of numerical values, optional) – if provided, these values are used to map the colors from the cmap

• color_mode (one of "auto", "uniform", "vertex", default "auto") – “uniform” restricts to a single color for all line datapoints. “vertex” allows independent colors per vertex. For most cases you can keep it as “auto” and the color_mode is determineed automatically based on the argument passed to colors. if colors represents a single color, then the mode is set to “uniform”. If colors represents a unique color per-datapoint, or if a cmap is provided, then color_mode is set to “vertex”. You can switch between “uniform” and “vertex” color_mode after creating the graphic.

• mode (one of: "markers", "simple", "gaussian", "image", default "markers") –

  The scatter points mode, cannot be changed after the graphic has been created.

  • markers: represent points with various or custom markers, default

  • simple: all scatters points are simple circles

  • gaussian: each point is a gaussian blob

  • image: use an image for each point, pass an array to the image kwarg, these are also called sprites

• markers (None | str | np.ndarray | Sequence[str], default "o") –

  The shape of the markers when mode is “markers”

  Supported values:

  • A string from pygfx.MarkerShape enum

  • Matplotlib compatible characters: “osD+x^v<>*”.

  • Unicode symbols: “●○■♦♥♠♣✳▲▼◀▶”.

  • Emojis: “❤️♠️♣️♦️💎💍✳️📍”.

  • A string containing the value “custom”. In this case, WGSL code defined by custom_sdf will be used.

• uniform_marker (bool, default True) – If True, use the same marker for all points. Only valid when mode is “markers”. Useful if you need to use the same marker for all points and want to save GPU RAM. If False, you can set per-vertex markers.

• custom_sdf (str = None,) –

  The SDF code for the marker shape when the marker is set to custom. Can be used when mode is “markers”.

  Negative values are inside the shape, positive values are outside the shape.

  The SDF’s takes in two parameters coords: vec2<f32> and size: f32. The first is a WGSL coordinate and size is the overall size of the texture. The returned value should be the signed distance from any edge of the shape. Distances (positive and negative) that are less than half the edge_width in absolute terms will be colored with the edge_color. Other negative distances will be colored by colors.

• edge_colors (str | np.ndarray | pygfx.Color | Sequence[float], default "black") – edge color of the markers, used when mode is “markers”

• uniform_edge_color (bool, default True) – Set the same edge color for all markers. Useful for saving GPU RAM. Set to False for per-vertex edge colors

• edge_width (float = 1.0,) – Width of the marker edges. used when mode is “markers”.

• image (ArrayLike, optional) – renders an image at the scatter points, also known as sprites. The image color is multiplied with the point’s “normal” color.

• point_rotations (float | ArrayLike = 0,) – The rotation of the scatter points in radians. Default 0. A single float rotation value can be set on all points, or an array of rotation values can be used to set per-point rotations

• point_rotation_mode (one of: "uniform" | "vertex" | "curve", default "uniform") –

  • uniform: set the same rotation for every point, useful to save GPU RAM

  • vertex: set per-vertex rotations

  • curve: The rotation follows the curve of the line defined by the points (in screen space)

• sizes (float or iterable of float, optional, default 1.0) – sizes of the scatter points

• uniform_size (bool, default False) – if True, uses a uniform buffer for the scatter point sizes. Useful if you need to save GPU VRAM when all points have the same size. Set to False if you need per-vertex sizes.

• size_space (str, default "screen") – coordinate space in which the size is expressed, one of (“screen”, “world”, “model”)

• kwargs – passed to Graphic

Return type:

ScatterGraphic

Examples

Scatter Animation Colors

Scatter Animation Colors

Scatter Animation Data

Scatter Animation Data