This is a quick-start guide that will help you install Xi-CAM and explore an example plugin that you can experiment with.
This guide does not explore the implementation of the plugin in too much detail. For more in-depth documentation for developing plugins from scratch, see:
If you haven’t already installed Xi-CAM, follow the installation instructions for your operating system:
In this guide we will:
Explore the main window of Xi-CAM
Download and install an Example Plugin
Configure a sample catalog so we can load data
Explore the Example Plugin
Here is a quick overview of some concepts that will be explored in this guide. Note that more documentation is available for each of these concepts.
We have one
this will be a plugin that you will be able to select and see within Xi-CAM.
The layout of the
GUIPlugin is defined by a
We have a few
These plugins are basically functions that take in data
and output derived data.
We also need a way to actually run data through the operations.
To do this, we have a
this contains linked operations to execute (can be thought of like a pipeline).
Looking at Xi-CAM’s Main Window¶
Let’s look at what the main window in Xi-CAM looks like first:
When Xi-CAM finishes loading, we see the window as shown above. Any installed GUIPlugins will be visible (and selectable) at the top (note that you will probably not have any installed yet).
We can also see some of the default widgets provided:
a welcome widget in the center of the window
a preview widget in the top-left (lefttop) of the window, which shows a sample of selected data in the data browser widget
a data browser widget on the left of the window, which can show available databroker catalogs
Quick GUILayout Overview¶
We mentioned the terms center, lefttop, and left above.
These correspond to positions in a
Here is a quick overview of how the Xi-CAM main window is organized:
You can see that the layout of Xi-CAM follows a 3x3 grid, where each section is named according to its orientation in relation to the center of the window.
(Note that any
GUIPlugins you create will have one or more of these
Download and Install the ExamplePlugin¶
Now that we have looked at the main window and its layout, let’s download the Example Plugin.
cd ~ git clone https://github.com/Xi-CAM/Xi-CAM.ExamplePlugin cd Xi-CAM.ExamplePlugin
What’s Inside the ExamplePlugin Repository¶
The repository will contain the following:
At the top there are a few files and directories:
setup.py- describes how to install this as a python package; also used to register plugins (via entry points).
configure- special directory for this example, helps set up a catalog
xicam- directory that acts as a python namespace package
xicam, there is a
exampleplugin subpackage that contains:
exampleplugina python package; also exposes the
exampleplugin.py- module that contains the
operations.py- module that contains the example
workflows.py- module that contains the example
How Do I Install the Example Plugin?¶
So far, we have only downloaded the Example Plugin - we still need to install it so Xi-CAM can find it and load it.
We can install downloaded plugins using a pip editable install:
pip install -e .
This uses Python’s entry points mechanism to register plugins for Xi-CAM to see.
Exploring the Example Plugin Interface¶
When you run
you should now see the Example Plugin available at the top right of the main window.
Select it and you should the Example Plugin layout:
In the center, we have a
CatalogView that will be used to display loaded data.
On the right, there is a
that shows the operations in the workflow
and allows for running the workflow.
At the bottom, there is a
DynImageView, which will be used to display the results data.
How Do I Load Data?¶
Now that we have the Example Plugin installed, we need to have data to load into it.
For purposes of this guide, we will be configuring a catalog called “example_catalog.”
For more information, see the Bluesky DataBroker documentation.
Configuring a Catalog¶
There is a
configure/ directory in the repository we cloned.
This contains a catalog configuration file, a msgpack catalog, and a script.
Feel free to inspect the script before you run it; it will attempt to set up a msgpack catalog source for Xi-CAM to use:
cd configure python setup_catalog.py cd ..
Loading a Catalog from the Data Resource Browser¶
Now that we’ve configured the catalog, let’s make sure that Xi-CAM can see it.
When loading a catalog into Xi-CAM, you must have a GUIPlugin active. Let’s select our “Example Plugin.”
Look at the Data Resource Browser on the left hand side of the window. The Data Resource Browser gives us access to two different types of data browsers by default:
a bluesky browser for catalogs (adapted from work done by NSLS-II)
a local file browser
After configuring our example catalog, the bluesky catalog browser should have the text “example_catalog” in the Catalog drop-down box.
Notice that it also has two text inputs, Since and Until. Our example catalog was created in the beginning of 2020. In order to see the data (catalogs) our “example_catalog” contains, we need to change the Since text input.
Change it’s value to “2020-01-01”. This will now look for any data that was created since the start of 2020. After making this change, the example_catalog will be re-queried for data created within these new dates.
You should see a catalog show up in the table below with the id 349497da. If you single-click the row in the table to highlight it, more information and a preview of the data should be shown as well. You can then open it with the “Open” button.
You should see Clyde the cat loaded into the center
Running a Workflow¶
Our Example Plugin has one internal workflow, the
ExampleWorkflow contains two
invert- inverts its input image
random_noise- applies random noise to its input image, has a “strength” parameter to define how much noise to apply to the image
This workflow is exposed in the GUI with a
WorkflowEditor on the right side of the layout.
Now that we have loaded some data, let’s run our workflow by clicking the “Run Workflow” button.
You should see an inverted picture with some random noise added to it.
Note that you can adjust the amount of random noise
by selecting the “random_noise” text in the
then changing the value of “strength” that shows up in the parameter tree above.
Examining the Code¶
Let’s take a quick look at how the code is implemented for our Example Plugin.
The code for this particular plugin is organized into three modules:
exampleplugin.py- Defines the
operations.py- Defines two
OperationPlugins: invert and random_noise
workflows.py- Defines an
ExampleWorkflowwith the invert and random_noise operations
Here we define
OperationPlugins (or operation)
An operation can be thought of as a function; input data is sent into the operation, and the operation generates some output with the given input.
When defining an
we use Python decorators (the
@ seen in the code).
At the very least,
you must provide the
@output_names decorators for an operation.
Here we define an
We add our two operations to the
then connect them so that
invert’s “output_image” value is sent to
random_noise’s input image argument.
Here we define the gui plugin
We provide a
name for the plugin,
which will display as “Example Plugin” in Xi-CAM.
We define our widgets, our layout,
and any internal objects we might need (like the workflow) inside of our
We connect the
This means whenever “Run Workflow” is clicked in the WorkflowEditor,
run_workflow method will be called.
We also define a
that will be called whenever our workflow has finished executing its operations.
callback_slot=self.results_ready in our
sets up this connection for us.