WIP

closes #389, closes #489, closes #499, closes #456, closes #369, closes #322, closes #316, closes #309, closes #283, closes #174, closes #147, closes #126

closes #507, closes #449, closes #123, closes #214

Remaining TODOs

• Use tiling for ImageGraphic
• refactor GraphicCollection
• more GraphicCollection implementation:
  • getters work
  • similar for non-sliceable graphics and those with uniform buffer for colors, ex:
    • line_stack.name = [f"line-{i}" for i in range(len(line_stack))]
• update TextGraphic with the feature changes.
• All tests

Summary

Graphic Features

• Changes how our Graphic Features are implemented, makes it easier for static type checking tools to understand them, slightly changes how they behave, see consider descriptor pattern for GraphicFeature. #389 for the original inspiration of this refactor, thanks @tlambert03 !!
• Modifes how events handlers can be added to a graphic, events refactor #456
• Makes the feature events more uniform across features, and simpler, Cleanup GraphicFeatures events pick_info  #174
• UniformBuffer can be used for lines and scatters, cannot be shared between graphics but maybe we can implement this later.
• Adds new GraphicFeatures, basically every graphic property which makes sense to be evented is a GraphicFeature, see Scope of graphic features #489. These features are common among all graphics:
  • Name: str, an optional name for the graphic
  • Offset: np.ndarray, [x, y, z], offset from the origin, NOT related to the data shown in the graphic, rename position_x, position_y, position_z to offsets #499
    • example: LineStack, lines are stacked along the y-axis w.r.t. to the rendering engine. This is done by incrementing the Offset. We DO NOT add to the actual data buffer that the graphic uses!
    • Rotation: np.ndarray, quaternion
    • Visible: bool
    • Deleted: bool - indicates if a a PlotArea has requested the deletion of a graphic. This is useful because you can add event handlers for "deleted", and this event handler can perform any necessary cleanup (disconnted events, etc.) so that the RAM for the graphic (i.e. the buffers) can be cleared.
• vmin, vmax are now their own features, no longer properties of ImageCmap. It was just cleaner this way and makes more sense because RGBA images have no cmap, but they can have vmin and vmax.
• Ownership of things is much cleaner. Graphic feature instances no longer keep the parent graphic as an attribute. Similarly, Graphics do not keep collection_index as an attribute.

Graphic Features that are sliceable, subclasses BufferManager

• Makes it possible to share buffers across graphics 😄 Look into sharing storage buffers  #126
  • buffers can be attached/detached, not yet tested. Graphic.attach_feature("feature_name") and Graphic.detach_feature("feature_name")
• All sorts of indexing works, including negative indexing, 16 test cases: https://github.com/fastplotlib/fastplotlib/blob/1d6adc6413e861b4a4ddc1f22fbe4c754b584a30/tests/utils.py
• The slice parser is much much simpler now, no more 🍝
• Only one color parser used for constructor and setter, also much simpler, less spaghetti
• A bunch of parameterized tests for slicing and setting these buffers
• BufferManager.__init__ manages whether the user's passed array should be isolated or not, the default is to create an isolated buffer. Makes much more sense to manage it here rather than in each SubGraphic.__init__. need to improve how we handle buffers #147
• Everything just gets casted to float32, Choose dtype for isolated buffer #369

Selector tools

• Deleted Sychronizer, this is something that a user should manage on their own, tailored to their usecase.
• The logic for getting the selected, index, indices, and selected data is much simpler.
  • All selector graphics set their offset to match the parent graphic's offset. This greatly simplifies things, no more adding/subtracting offsets to map from world-space -> data space 😄
  • The geometry of the selector tool's underlying WorldObjects are used to get the position/region under the selection. Since the offsets match those of the parent Graphic, we don't need to do anything more.
  • the "selection" feature now returns value(s) in data space, NOT INDICES. This makes more sense since for example, you would want to set or get the bounds of a LinearRegionSelector in terms of actual (data xmin, data xmax). Likewise for LinearSelector.
• Selectors behave a bit better, example: LinearRegionSelector behaves more intuitively when at/close to the limits. It is not actually possible to "smash" the selector right up against the limits and it actually touches the limit, whereas before if the delta was a bit larger it would be stuck a few pixels away from the limit.
• The events are simplified (see below)

API comparision

Basic features (no buffer)

# before this PR, setting and getting a feature value
>>> line_graphic.thickness = 3.5
>>> line_graphic.thickness()
3.5

# this PR, getter & setter are symmetric when possible
>>> line_graphic.thickness = 3.5
>>> line_graphic.thickness
3.5

Sliceable features (manages a buffer)

# setting and getting the "entire value"
>>> line_graphic.colors = "r"
>>> line_graphic.colors
<__repr__ prints array>

# this PR, similar but value can be directly access if desired
>>> line_graphic.colors = "r"
>>> line_graphic.colors
<__repr__ prints array>

>> line_graphic.colors.value
<returns the actual array>

Sharing buffers 😄 !

# let's say you have a line with some vertex colors
>>> line1.colors
<returns array for red>

>>> line2 = subplot.add_line(data, colors=line1.colors)  # share buffer :D !

# modify colors
>>> line2.colors[50:] = "b"

# change of colors is reflected in BOTH graphics :D 

The implementation is very simple, for example in PositionsGraphic.__init__:

class PositionsGraphic(Graphic):
  def __init__(self, data, colors, ...):
    if isinstance(data, VertexPositions):
        self._data = data
    else:
        self._data = VertexPositions(data, isolated_buffer=isolated_buffer)

As we can see, it actually shares the BufferManager (i.e. feature) instance. This is simpler and makes it so changing the buffer causes events to be emitted even if it's from another graphic. In the above example, if an event handler is added to line1, i.e. line1.add_event_handler(<callable>, "colors"), then changing the colors of line2 would also trigger the event which I assume is what you would want since line1 colors have also changed.

Events

# before this PR
line_graphic.thickness.add_event_handler(<callable>)

# this PR
line_graphic.add_event_handler(<callable>, "thickness")

# can also use decorators :D

@line_graphic.add_event_handler("thickness")
def thickness_changed_handler(ev):
  pass

# exactly the same for features that subclass BufferManager
@line_graphic.add_event_handler("colors", "data")
def line_colors_or_data_changed(ev):
  if ev.type == "colors":
    print(
      f"colors changed for graphic: <{ev.graphic}> 
      F"with slice: {ev.info['key']} and new values: {ev.info['value']}"
  )
  if ev.type == "data":
    print(
      f"data changed for graphic: <{ev.graphic}> 
      F"with slice: {ev.info['key']} and new values: {ev.info['value']}"
  )

# rendering engine events added in exactly the same way
@image_graphic.add_event_handler("click")
def image_clicked(ev):
  ev.graphic # the graphic that caused the event

The event adding and handling is managed here:

Before this PR, the event info was a mess that we probably don't need to dig into 😆 . Now every FeatureEvent inherits from pygfx.Event and has the following attributes:

The "info" dict for all "simple" features has one key, "value", which is the user passed new value. Example if line_graphic.name is changed, then the info dict will be: {"value": "new_name_str"}

BufferManager example info dicts:

colors (vertex colors, line or scatter)

data (points data, line or scatter)

Selectors

Adding event handlers to a selector is identical to how they're added for "regular" graphics:

# one of the selectors will change the line colors when it moves
@selector.add_event_handler("selection")
def set_color_at_index(ev):
    # changes the color at the index where the slider is
    ix = ev.get_selected_index()
    g = ev.graphic.parent
    g.colors[ix] = "green"

Selector feature event structure

LinearSelector "selection"

additional event attributes:

info dict:

LinearRegioonSelector

additional event attributes:

info dict:

This is how it's implemented:

selector is the LinearSelector (in this case) or LinearRegionSelector that the feature manages, and it has the get_selected_index, or get_selected_indices and get_selected_data methods for LinearRegionSelector

Graphics

Some major refactor to graphics not mentioned above:

• line and scatter graphics now inherit from a common PositionsGraphic that handles things that are common between lines and scatters (data, colors, etc.)