Stage plugins

Defines a plugin architecture so that new stages can be defined at runtime and made available to the StageFactoryBase used in the GUI to list available stages, and for analysis.

ceed.stage.register_all_stages() is called by the GUI and it registers any plugin stages with the ceed.stage.StageFactoryBase used by the GUI for managing stages. ceed.stage.register_all_stages() internally calls get_plugin_stages() to get all the stages exported by all the Python plugin module files in the ceed/stage/plugin directory and registers them with the ceed.stage.StageFactoryBase.

Additionally, if the user provides a package name in the external_stage_plugin_package configuration variable, the GUI will similarly import and register the plugins in that package with ceed.stage.register_external_stages(). The package must however be a proper python package that can be imported. E.g. if external_stage_plugin_package is my_ceed_plugin.stage, Ceed will try something roughly like from my_ceed_plugin.stage import get_ceed_stages.

Files in ceed/stage/plugin that want to define new stage classes should define a function in the file called get_ceed_stages that returns a list of stages that will be automatically registered with the stage factory StageFactoryBase using register().

To write a plugin, familiarize yourself with CeedStage, it’s properties, and relevant methods that need to be overridden. Some relevant methods are get_gui_props(), get_state(), get_noise_supported_parameters(), get_prop_pretty_name(), init_func_tree(), init_func(), init_loop_iteration(), get_relative_time(), and resample_parameters().

__call__() is how the function is called. It takes the time in global time so it should convert it to function local time with get_relative_time() and then return the function value.

See the ceed/stage/plugin/__init__.py file and get_ceed_stages() for an example plugin (currently the internal plugin doesn’t actually define any new stages).

ceed.stage.plugin.get_plugin_stages(stage_factory: ceed.stage.StageFactoryBase, base_package: str, root: Union[str, pathlib.Path]) → Tuple[List[Type[ceed.stage.StageType]], List[Tuple[Tuple[str], bytes]]]

Imports all the .py files in the given directory and sub-directories for the named package that don’t start with a underscore (except for __init__.py of course, which is imported). For each imported module, it calls its get_ceed_stages function (if they are defined in the module) which should return a list (that can be empty) of all the stages classes exported by the module.

It then returns all these exported stages and all the file contents in the folder.

Ceed will automatically import all the plugins under ceed/stage/plugin.

Parameters

stage_factory – The StageFactoryBase instance with which the returned plugin stages will be registered.
base_package – The package name from which the plugins will be imported. E.g. to import the plugins in ceed/stage/plugin, base_package is ceed.stage.plugin because that’s the package containing name for the plugin directory. Then, they are imported as ceed.stage.plugin and ceed.stage.plugin.xyz, if the plugin directory also contains a xyz.py plugin file.
root – The full directory path that contains the plugins. E.g. for ceed.stage.plugin it is ceed/stage/plugin.

Returns

A tuple with two values containing: a list of stage classes exported by all the modules and a list containing all the python files contents encountered in the directory.

The python files contents are returned so that Ceed can store it in the data files in case the plugins are changed between experimental runs.

See get_ceed_stages() and register_all_stages() for an example how it’s used.

ceed.stage.plugin.get_ceed_stages(stage_factory: ceed.stage.StageFactoryBase) → Iterable[Type[ceed.stage.StageType]]

Returns all the stage classes defined and exported in this file (currently none for the internal plugin).

Parameters: stage_factory – The FunctionFactoryBase instance currently active in Ceed.

class ceed.stage.plugin.CSVStage(**kwargs)

Bases: ceed.stage.CeedStage

Defines a stage whose shape frame values are read from a csv file.

The format of the CSV file is one column for each shape and color channel. The top row contains the name of the shape followed by an underscore and the color channel. E.g. if the shape is named circle and we have values for its red channel, then the column name will be circle_red.

The remaining rows, each row in the column is the value of that shape’s color channel for one frame. The total duration of the stage is the number of frames (rows) divided by the frame rate. I.e. each row corresponds to a frame, but the depending on the fps in Ceed it can be displayed at different times.

Color channels not provided in the file are not set by the stage. E.g. if the file only had one column headed with circle_red, the circle’s green and blue channels won’t be set.

Values are forced to the [0, 1] range.

csv_path: str: The full path to the CSV file.

get_state(*args, **kwargs) → dict

Returns a dict representation of the stage so that it can be reconstructed later with apply_state().

Params

state: dict: A dict with the state, to which configuration items and their values are added. If None, the default, a dict is created and returned.

Returns

A dict with all the configuration data.

add_func(*args, **kwargs) → None

Adds the function instance ceed.function.FuncBase to functions.

Parameters

func – The ceed.function.FuncBase to add.
after – The ceed.function.FuncBase in functions after which to add this function, if not None, the default.
index – The index in functions at which to add this function, if not None, the default.

add_stage(*args, **kwargs) → None

Adds a sub-stage instance CeedStage to stages.

Parameters

stage – The CeedStage or ref to add.
after – The CeedStage in stages after which to add this stage, if not None, the default.
index – The index in stages at which to add this stage, if not None, the default.

add_shape(*args, **kwargs) → None

Creates and adds a StageShape instance wrapping the ceed.shape.CeedShape shape to the shapes. If the shape was already added it doesn’t add it again.

Params

shape: ceed.shape.CeedShape: The shape instance to add.

Returns

The StageShape created if the shape wasn’t already added, otherwise None.

get_settings_display(*args, **kwargs) → Dict[str, Any]

Returns widgets that will be displayed to the user in the stage settings.

These widgets can be used to allow users to further configure custom stages. This is called by the Ceed GUI when the settings are first displayed to the user.

Parameters: stage_widget – The root settings widget to which the settings will be added as grandchildren by the caller.
Returns: It should return a dict of the name of each setting mapped to the widget controlling the setting. It will be displayed in two columns: the name followed by the widget on the same row.

init_stage_tree(*args, **kwargs) → None

Before the stage is apply_pre_compute() and started, the stage and all sub-stages are recursively initialized.

Initializes the stage as part of the stage tree so it is ready to be called to get the stage values as part of the tree. It is called once for each stage of the entire stage tree.

Parameters: root – The root of the stage tree. If None, it’s self.

tick_stage_loop(shapes, last_end_t): If the stage was not pre-computed, ticks through one loop iteration of the stage yielding the shape values for each time-point.

get_stage_shape_names()

Gets all the names of the shapes controlled by the stage or substages. If adding names, you must call super to get the builtin shapes.

It calls get_stage_shape_names() on its children, recursively, so any of them can be overwritten to return arbitrary names (that must be unique among all the shapes).

This is used to create the shape logs in the HDF5 data file. Because for each shape we create a Nx4 array, where N is the number of Ceed time frames, and 4 is for the RGBA value for that frame (shapes_intensity).

By default, it gets the name of the shapes from shapes from itself and its children stages. If you’re directly updating the graphics, you can log rgba values by returning additional names here and then setting their values when the stage is ticked, as if it was a real shape. The values will then be accessible in shapes_intensity.

If you set the values of the additional shapes when the stage is ticked, then the values will also show in the stage preview graph so you can use it to display arbitrary rgb data for your stage in the graph. But it must be logged during stage tick (e.g. evaluate_stage()), not during the actual graphing in set_gl_colors() that follows each tick.

See the stage example plugins for example usage.