add_scatter_collection#

Subplot.add_scatter_collection(data, *, colors='w', cmap=None, cmap_transform=None, cmap_range=None, mode='markers', markers='o', custom_sdf=None, edge_colors='black', edge_width=1.0, image=None, point_rotations=0.0, sizes=5, size_space='screen', names=None, offsets=None, rotations=None, scales=None, alphas=None, alpha_modes=None, visibles=None, metadatas=None, name=None, offset=(0.0, 0.0, 0.0), rotation=(0.0, 0.0, 0.0, 1.0), scale=(1.0, 1.0, 1.0), alpha=1.0, alpha_mode='auto', visible=True, metadata=None)#

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 (ColorLike or MultiColorLike, 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 (ColormapLike, 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 (np.ndarray, optional) – 1D array-like or list of numerical values, these values are used to map the colors from the cmap

  • cmap_range ((float, float), optional) – the (min, max) of the cmap_transform mapped onto the colormap, defaults to the transform’s own range

  • 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 (str | np.ndarray | Sequence[str], default "o") –

    The shape of the markers when mode is “markers”. Specify a single marker to use the same marker for all points, or a Sequence of markers for per-vertex 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.

  • 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 (ColorLike, MultiColorLike, or None, default "black") – edge color(s) of the markers, used when mode is “markers”. Specify a single color to use the same edge color for all markers, or a Sequence of colors for per-vertex edge colors. Pass None for no edge color.

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

  • image (array-like, 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, array-like, or None, default 0.0) – The rotation of the scatter points in radians. The rotation mode is determined automatically from the value: pass None (default) for “curve” mode, where each point’s rotation follows the curve of the data (in screen space); a single float for the same rotation on every point (“uniform”); or an array of rotation values for per-point rotations (“vertex”). Units are in radians.

  • sizes (float, np.ndarray, or Sequence[float], default 5) – size(s) of the scatter points. Specify a single size to use the same size for all points, or a Sequence of sizes for per-point 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:

Graphic