Stage widgets

Defines the GUI components used with ceed.stage.

class ceed.stage.stage_widgets.StageList(**kwargs)

Bases: kivy_garden.drag_n_drop.DraggableLayoutBehavior, ceed.graphics.ShowMoreSelection, ceed.graphics.WidgetList, kivy.uix.boxlayout.BoxLayout

Widget that shows the list of available stages to the user and also allows for the creation of new stages to be added to the list.

The functions come from ceed.stage.StageFactoryBase.

is_visible

Whether the list is currently visible.

It is used by the selection logic and it’s always True for this class.

stage_factory: ceed.stage.StageFactoryBase = None: The ceed.stage.StageFactoryBase that is used for the list of stages available to the user and with whom new stages created in the GUI are registered.

remove_shape_from_stage(stage: ceed.stage.CeedStage, stage_shape: ceed.stage.StageShape)

This is called to remove a shape from being referenced by a stage.

Parameters

stage – The CeedStage that references the shape.
stage_shape – The StageShape to be removed.

add_stage(name: str) → None: Adds a copy of the the stage with the given name from stage_factory to the available stages in stage_factory (with a new name of course) or to a stage.

handle_drag_release(index, drag_widget)

This is called when a widget is dropped in the layout. index is the index in children where the widget should be added. drag_widget is the DraggableObjectBehavior that was dropped there.

This must be overwritten by the inherited class to actually do the add_widget or something else.

get_selectable_nodes()

(internal) Returns a list of the nodes that can be selected. It can be overwritten by the derived widget to return the correct list.

This list is used to determine which nodes to select with group selection. E.g. the last element in the list will be selected when home is pressed, pagedown will move (or add to, if shift is held) the selection from the current position by negative page_count nodes starting from the position of the currently selected node in this list and so on. Still, nodes can be selected even if they are not in this list.

Note

It is safe to dynamically change this list including removing, adding, or re-arranging its elements. Nodes can be selected even if they are not on this list. And selected nodes removed from the list will remain selected until deselect_node() is called.

Warning

Layouts display their children in the reverse order. That is, the contents of children is displayed form right to left, bottom to top. Therefore, internally, the indices of the elements returned by this function are reversed to make it work by default for most layouts so that the final result is consistent e.g. home, although it will select the last element in this list visually, will select the first element when counting from top to bottom and left to right. If this behavior is not desired, a reversed list should be returned instead.

Defaults to returning children.

clear_all(): Removes all the widgets associated with the registered stages in stage_factory from the GUI.

show_stage(stage, expand_stage=True)

Displays the widget of the stage in the GUI. This is for displaying registered stages, not a sub-stage.

Parameters

stage – The CeedStage to show.
expand_stage – Whether to expand the stage options in the GUI. If true the user could e.g. edit the name without having to click first to expand the edit options.

show_sub_stage(stage: Union[ceed.stage.CeedStage, ceed.stage.CeedStageRef], parent_stage: ceed.stage.CeedStage)

Displays the widget of the stage in the GUI. This is for displaying a sub-stages within the parent stage.

Parameters

stage – The CeedStage to show.
parent_stage – The parent CeedStage within which to show the stage.

show_shape_in_stage(stage: ceed.stage.CeedStage, shape: ceed.stage.StageShape)

Displays the widget of the shape in the GUI as belonging to the stage.

Parameters

stage – The CeedStage to show.
shape – The StageShape to display.

copy_and_resample_experiment_stage(stage_name, set_ceed_id: bool = False)

Makes a stage ready to be run as an experiment.

It takes the stage, copies it and expands all sub-stages that are references, then samples all the parameters and finally adds this copied stage to the stage_factory. See copy_and_resample().

The copied stage is then named last_experiment_stage_name. If a stage with that name already exists, that stage is first removed.

Parameters

stage_name – The name of the registered stage to copy.
set_ceed_id – If True, we call set_ceed_id() with argument zero on the newly copied root stage to set the stage/sub-stages and functions unique IDs.

class ceed.stage.stage_widgets.StageWidget(**kwargs)

Bases: ceed.graphics.ShowMoreBehavior, kivy.uix.boxlayout.BoxLayout

The widget displayed for an ceed.stage.CeedStage instance.

stage: Union[ceed.stage.CeedStage, ceed.stage.CeedStageRef] = None: The ceed.stage.CeedStage or ceed.stage.CeedStageRef instance attached to the widget.

ref_stage = None: If stage is a ceed.stage.CeedStageRef, this is the actual ceed.stage.CeedStage stage is internally referencing. Otherwise, it’s None.

selected: Whether the stage is currently selected in the GUI.

stage_widget: ceed.stage.stage_widgets.StageChildrenList = None: The internal widget container to which children StageWidget widget instances are added.

func_widget: ceed.stage.stage_widgets.StageFuncChildrenList = None: The internal widget container to which children ceed.func_widgets.FuncWidget or ceed.func_widgets.FuncWidgetGroup widget instances are added.

shape_widget: ceed.stage.stage_widgets.StageShapesChildrenList = None: The internal widget container to which children StageShapeDisplay widget instances are added.

is_visible: Whether the stage is currently visible in the GUI. I.e. when all of it’s parents all the way to the root is visible.

selection_controller = None: The container that gets called to select the stage widget when the user selects it with a touch. E.g. StageList in the global stage listing case or StageChildrenList if it belongs to a stage.

settings_root = None: The dropdown used by this function to show settings.

expand_widget = None: The widget that when pressed will expand to show the more widget.

property name: The ceed.stage.CeedStage.name of the stage.

get_visible_children(): Iterates and yields all the widgets representing the sub-stages, functions, and shapes belonging to the stage, including the stage’s widget itself, if they are visible. The currently collapsed/hidden widgets are skipped.

initialize_display(stage, selection_controller): Sets selection_controller and generates and applies the kv GUI rules for the widget and it’s children (sub-stages, functions, and shapes).

remove_stage_from_factory_no_ref()

Removes the stage from the stage_factory and GUI.

This can only be called if the stage is not representing a CeedStageRef.

remove_stage(): Removes the stage from the stage_factory and from the GUI.

replace_ref_with_source(): If this stage is a ceed.stage.CeedStageRef, this will replace the reference with the a copy of the original stage being referenced and the GUI will also be updated to reflect that.

apply_kv()

Applies the kv rules to the widget.

The rules are manually applied to the class because we want to have a chance to initialize some instance variables before the kv rules is applied so they can be referred to from kv without having to check if they are None.

create_settings_dropdown(): Creates the dropdown widget that displays the stage’s configuration options.

add_stage_containers(more_widget)

Adds the widget containers for the sub-stage, functions, and shapes widgets of this stage.

Parameters: more_widget – The widget to which the containers are added. This widget can be made invisible in the GUI.

class ceed.stage.stage_widgets.StageChildrenViewList(**kwargs)

Bases: kivy_garden.drag_n_drop.DraggableLayoutBehavior, kivy.uix.boxlayout.BoxLayout

The base class used by the GUI to list a stages functions, stages, or shapes.

is_visible: Whether the list is currently expanded and visible to the user.

stage_widget: ceed.stage.stage_widgets.StageWidget = None: The StageWidget to whom this widget belongs.

class ceed.stage.stage_widgets.StageChildrenList(**kwargs)

Bases: ceed.stage.stage_widgets.StageChildrenViewList

The container that displays the stage’s sub-stage children in the GUI.

handle_drag_release(index, drag_widget)

This is called when a widget is dropped in the layout. index is the index in children where the widget should be added. drag_widget is the DraggableObjectBehavior that was dropped there.

This must be overwritten by the inherited class to actually do the add_widget or something else.

class ceed.stage.stage_widgets.StageFuncChildrenList(**kwargs)

Bases: ceed.stage.stage_widgets.StageChildrenViewList

The container that displays the stage’s functions in the GUI.

static handle_func_drag_release(index, drag_widget, selection_controller, stage)

Takes a function widget being dragged into the stage and adds the function to the stage and creates the widget to display the function.

Parameters

index – The index where the widgets was dragged into.
drag_widget – The widget being dragged.
selection_controller – The controller that handles selection for the list into which the function was dragged into.
stage – The associated stage.

Returns

The widget created to display the function.

handle_drag_release(index, drag_widget)

This is called when a widget is dropped in the layout. index is the index in children where the widget should be added. drag_widget is the DraggableObjectBehavior that was dropped there.

This must be overwritten by the inherited class to actually do the add_widget or something else.

class ceed.stage.stage_widgets.StageShapesChildrenList(**kwargs)

Bases: ceed.stage.stage_widgets.StageChildrenViewList

The container that displays the stage’s shapes in the GUI.

handle_drag_release(index, drag_widget)

This is called when a widget is dropped in the layout. index is the index in children where the widget should be added. drag_widget is the DraggableObjectBehavior that was dropped there.

This must be overwritten by the inherited class to actually do the add_widget or something else.

class ceed.stage.stage_widgets.StageShapeDisplay(**kwargs)

Bases: ceed.graphics.BoxSelector

The widget used to display a ceed.stage.StageShape representation of the shape in the stage.

stage_shape: ceed.stage.StageShape = None: The ceed.stage.StageShape instance that this widget displays.

selected: Whether the widget is currently selected. Read only.

selection_controller = None: The container that gets called to select the shape widget when the user selects it with a touch.

is_visible: Whether the shape is currently visible in the stage shape’s list.

settings_root = None: The dropdown configuring the shape.

property name: The ceed.stage.StageShape.name of the shape or shape group.

initialize_display(stage_shape, selection_controller): Sets selection_controller and generates and applies the kv GUI rules for the widget (StageShapeDisplayStyle).

remove_shape(): Removes the shape from being referenced by the stage and also removes it from the GUI.

create_settings_dropdown(): Creates the dropdown widget that displays the shape’s configuration options.

class ceed.stage.stage_widgets.ShapePlot(name='', graph_canvas=None, graph=None, **kwargs)

Bases: object

A plot that displays the time-intensity series of a shape in r, g, b seperately.

r_plot = None: The MeshLinePlot used by the red color.

g_plot = None: The MeshLinePlot used by the green color.

b_plot = None: The MeshLinePlot used by the blue color.

r_btn = None: The button in the GUI that controls whether the red color is displayed.

g_btn = None: The button in the GUI that controls whether the green color is displayed.

b_btn = None: The button in the GUI that controls whether the blue color is displayed.

color_values = None: A Tx4 numpy array with the values r, g, b, a for all time points.

frame_rate = 30.0: The sampling rate used to sample the plot across time.

name = '': The name of the shape displayed by this plot.

graph = None: The StageGraph that displays this p;ot.

graph_canvas = None: The canvas to which the plot graphics instructions are added.

background = []: A list that contains the color graphics instructions used to color the back of each plot.

selection_label = None: The label that shows the plot name next to the color selection.

plot_label = None: The label used on the plot to label the plot.

update_plot_instructions(): Updates the graphics instructions when the plot is shown/hidden. Returns True when the plot was shown/hidden and False otherwise.

remove_plot(): Removes the r, g, b plots from the graph and hides them.

update_plot_params(rect, xmin, xmax, start, end, time, factors)

Updates the paraeters of the plot, e.g. the time range displayed etc.

Params

rect: 4-tuple: (x1, y1, x2, y2), where x1, y1, is the position of the lower-left corner of the screen area that displays the plot and x2, y2 is the upper-right position.
xmin: float: Similar to StageGraph.xmin.
xmax: float: Similar to StageGraph.xmax.
start: int: The index in time in color_values from where to display the data.
end: int: The index in time in color_values until where to display the data.
time: numpy array: A numpy array with the time values of the for the data to be displayed.
factors: list of ints: A list of successive factors by which color_values needs to be decimated so that it’ll match time. We down-sample when the data is too large.

update_plot_sizing(rect)

Updates only the physical position of the plot on screen.

Params

rect: 4-tuple: (x1, y1, x2, y2), where x1, y1, is the position of the lower-left corner of the screen area that displays the plot and x2, y2 is the upper-right position.

force_update(): Simply forces a re-draw of the plot using the last settings.

class ceed.stage.stage_widgets.StageGraph(**kwargs)

Bases: kivy.factory.FlatSplitter

Displays a time-intensity plot for all the shapes of a ceed.stage.CeedStage.

plot_values: The computed intensity values for the shapes for all times as returned by get_all_shape_values().

plots: A dict whose keys are the name of shapes and whose values are the ShapePlot instances visualizing the shape.

n_plots_displayed: The number of ShapePlot currently displayed. Read-only.

shape_height: The height of each plot.

shape_spacing: The spacing between plots.

xmin: The min time of the whole data set. This is the start time of the data.

xmax: The max time of the whole data set. This is the end time of the data.

view_xmin: The visible start time of the graph being displayed.

view_xmax: The visible end time of the graph being displayed.

r_selected

Which of the shape’s plots is currently shown for the red color.

Can be one of 'all', 'none' 'some'.

g_selected

Which of the shape’s plots is currently shown for the green color.

Can be one of 'all', 'none' 'some'.

b_selected

Which of the shape’s plots is currently shown for the blue color.

Can be one of 'all', 'none' 'some'.

time_points = []: The list of time points for which the shapes have an intensity value. It’s in the range of (xmin, xmax). It is automatically set by refresh_graph().

frame_rate = 1.0: The sampling rate used to sample the shape intensity values from the functions in time. It is automatically set by refresh_graph().

property sorted_plots: A list of tuples of the key, value pairs of plots sorted by shape (plot) name.

refresh_graph(stage_name: str, frame_rate)

Re-samples the intensity values for the shapes from the stage.

Params

stage_name: str: The stage from which to sample the shape intensity values.
frame_rate: float: The sampling rate used to sample the shape intensity values from the functions in time.

sync_plots_shown(*largs): Checks which plots were selected/deselected in the GUI and shows/hides the corresponding plots.

apply_selection_all(channel)

Hides or shows all the plots for a color channel, e.g. red, depending on the state of the corresponding :attr:`` r_selected.

It cycles between selecting all and derselecting all of that channel.

Params

channel: str: One of 'r', 'g', or 'b'.

refresh_plot_pos(*largs): Called when any of the plot parameters, e.g. xmax or view_xmax, changes and the plots needs to be updated.

refresh_plot_sizing(*largs): Called when the physical position of the graph needs to be updated but none of the parameters of the graph has changed.

set_pin(state)

Switches between the graph being displayed as a pop-up and as inlined in the app.

Params

state: bool: When True, the graph will be displayed inlined in the app. When False it is displayed as pop-up.