Difference between revisions of "Op Finder"

(For Users)
Line 23: Line 23:
 
= Parts of the Op Finder =
 
= Parts of the Op Finder =
  
[[File:LabeledOpFinder.png]]
+
: [[File:LabeledOpFinder.png]]
  
 
'''Labeled components'''
 
'''Labeled components'''
Line 43: Line 43:
 
= Views =
 
= Views =
  
There is a lot of information surrounding Ops. One goal of the Op Finder is to present this information in a way that can be easily understood. To facilitate this, multiple views are available, tailoring the content of the Op Finder to a particular audience.
+
Because of the extensibility of Ops, there is a lot of information to process when looking at what Ops are actually available. One goal of the Op Finder is to present this information in a way that can be easily understood. To facilitate this, multiple views are available, each tailoring the content of the Op Finder to a specific audience.
  
 
== For Users ==
 
== For Users ==
  
{{Warning|This view does not provide an accurate representation of real Ops e.g., one entry could be many Ops merged together. An Op call is ultimately defined by the combination of requested Op + parameters.}}
+
{{Warning|This view provides an abstract representation of available Ops e.g., one entry could be many Ops merged together. An Op call is ultimately defined by the combination of requested '''Op type''' + '''parameters'''.}}
  
Ops in this view are focused on answering the question "What can I do ''right now'' with Ops?" The following guidelines are used to create this list:
+
Ops in this view are focused on answering the question "What can I do ''right now'' with Ops?" For example, in this example we see that we can call the <code>Convolve</code> Op with either a base image, or the base and kernel:
  
 +
: [[File:UserOpFinder.png|border|800px]]
 +
 +
'''User View Contents'''
 
* Only Ops directly involving images are displayed
 
* Only Ops directly involving images are displayed
* Parameter types are generalized
+
* Parameter types are abstracted ("Image", "Number")
 
* Optional parameters are hidden
 
* Optional parameters are hidden
  
 
== For Developers ==
 
== For Developers ==
  
* Details pane open by default
+
This view provides a comprehensive list of available Ops implementations. For example, contrasting with the [[#For Users|User view]], we see there are actually four concrete implementations of the <code>Convolve</code> Op, with a plethora of optional parameters.
* Precise Op signature
+
 
* Optional parameters are shown
+
: [[File:DevOpFinder.png|border|800px]]
* Referring class is shown
+
 
 +
'''Developer View Contents'''
 +
# Precise Op signature
 +
# Code snippet for use
 +
# Defining Op class
  
 
= Things to do =
 
= Things to do =
Line 66: Line 73:
 
== Filtering ==
 
== Filtering ==
  
TODO fuzzy, no namespaces
+
The Op Finder includes [[Wikipedia:Approximate_string_matching|fuzzy filtering]] to find Ops of interest. When filtering:
  
== Running Ops ==
+
* Namespaces are hidden
 +
* In [[#For Users|User view]], the complete simplified Op entry is filtered.
 +
* In [[#For Developers|Developer view]], the Op namespaces + class name are filtered.
  
TODO how does the play button work?
+
[[File:Filter-op-finder.png|border|600px]]
  
 
== Code Snippets ==
 
== Code Snippets ==
  
TODO take a code snippet and turn it into a script, step-by-step
+
Code snippets are available in the [#For Developers|Developer view]]. These are intended to help you rapidly build up scripts around the available Ops. The following is a step-by-step guide to take you through the process of finding an Op of interest to using it in a functional script.
  
 
1. The first thing to do is find an Op of interest. In this case, we start from the [[#For Users|User view]] and see that there is a Convolve Op we want to try:
 
1. The first thing to do is find an Op of interest. In this case, we start from the [[#For Users|User view]] and see that there is a Convolve Op we want to try:
Line 125: Line 134:
  
 
[[File:4-run-op.png|border"1200px]]
 
[[File:4-run-op.png|border"1200px]]
 +
 +
== Running Ops ==
 +
 +
Although you can run selected Ops through the Op Finder, this method '''lacks reproducibility''' and should not be used as a substitute for a proper script or plugin when using Ops in a scientific workflow. This functionality ''is'' intended to allow a rapid preview of what effect an Op will have on a dataset.
 +
 +
The [[#Parts of the Op Finder|play button]] essentially automates the process of turning an Op [[#Code Snippets|into a script]]: optional parameters are discarded and required parameters are [[Script_parameters|annotated]]. Because of this, Ops with arcane or unusual parameters may fail to run because the framework does not know how to provide them.
 +
 +
Thus it is recommended to run Ops primarily from the [[#For Users|User view]], as these Ops focus on images and numbers, which can automatically be provided by the framework (via open images and input panels, respectively).

Revision as of 13:12, 3 May 2016

Op Finder (ImageJ)
Author Mark Hiner
Maintainer Mark Hiner, Ctrueden
File net.imagej:op-finder
Source on GitHub
Initial release April 2016
Latest version April 2016
Development status beta
Category Plugins


The Op Finder is a utility for browsing, learning about and running all available Ops. Because Ops are plugins and can be dynamically extended and specialized for particular inputs, it is not practical to have static documentation on a given Op. By using the Op Finder, you explore the actual list of Ops available in your installation. The purpose of this guide is to familiarize you with the basic capabilities of the Op Finder, to enable you to learn and experiment with Ops.

Getting started

There are two ways to start up the Op Finder:

  1. Using the shortcut: Shift+L
  2. Using the menu path: Plugins › Utilities › Find Ops...

Parts of the Op Finder

LabeledOpFinder.png

Labeled components

  1. Search bar for filtering the list of Ops.
  2. Toggle button to change between a user and developer view.
  3. Play button for running the selected Op.
  4. Copy button to copy the selected cell contents.
  5. Help button to open up the Wiki reference page in your browser.
  6. Status area showing success/failure notifications e.g., for copying or running Ops.
  7. Namespaces and Op types: these can be expanded to explore the tree-based organization of Ops.
  8. Op implementation: the leaves of this tree tell us what parameter options are available for each Op type. We interpret this particular example as "There is an Add Op in the Math namespace, that operates on an image and a numeric value".
  9. Progress area showing progress when performing lengthy operations, such as filtering the Ops.
  10. Details pane toggle. Click this button to show/hide a pane containing additional information about the currently selected Op.

Additional features

  • Hover your mouse over any part of the Op Finder to get a descriptive tool-tip.
  • Double-click any cell to copy its contents to your clipboard.

Views

Because of the extensibility of Ops, there is a lot of information to process when looking at what Ops are actually available. One goal of the Op Finder is to present this information in a way that can be easily understood. To facilitate this, multiple views are available, each tailoring the content of the Op Finder to a specific audience.

For Users



Ops in this view are focused on answering the question "What can I do right now with Ops?" For example, in this example we see that we can call the Convolve Op with either a base image, or the base and kernel:

UserOpFinder.png

User View Contents

  • Only Ops directly involving images are displayed
  • Parameter types are abstracted ("Image", "Number")
  • Optional parameters are hidden

For Developers

This view provides a comprehensive list of available Ops implementations. For example, contrasting with the User view, we see there are actually four concrete implementations of the Convolve Op, with a plethora of optional parameters.

DevOpFinder.png

Developer View Contents

  1. Precise Op signature
  2. Code snippet for use
  3. Defining Op class

Things to do

Filtering

The Op Finder includes fuzzy filtering to find Ops of interest. When filtering:

  • Namespaces are hidden
  • In User view, the complete simplified Op entry is filtered.
  • In Developer view, the Op namespaces + class name are filtered.

Filter-op-finder.png

Code Snippets

Code snippets are available in the [#For Developers|Developer view]]. These are intended to help you rapidly build up scripts around the available Ops. The following is a step-by-step guide to take you through the process of finding an Op of interest to using it in a functional script.

1. The first thing to do is find an Op of interest. In this case, we start from the User view and see that there is a Convolve Op we want to try:

1-select-op.png

2. In the Script Editor, we need to add a reference to the OpService which will be our entry point for Op usage:

# @OpService ops
Note: this guide is written in Python but any scripting language will work

3. Now we need the code call for our Convolve Op, so we switch to the Developer view. The code is long, but remember we can copy:

2-op-snippet.png
and paste:
# @OpService ops

ops.run("filter.convolve", Img, Img, RandomAccessibleInterval, long[], OutOfBoundsFactory, OutOfBoundsFactory, RealType, ImgFactory)

4. Looking at the Op call, we see that there are a lot of parameters. To get a better idea of what these are, we look at the Op Signature column of the Op Finder:

3-op-signature.png
All of the parameters with a ? are optional. For our purposes, let's just work with the input image, kernel, and returned image:
# @OpService ops

out = ops.run("filter.convolve", Img, RandomAccessibleInterval)

5. Now we need to get inputs for our Op, and ensure the output is displayed. These tasks can all be handled with additional @Parameters to the script:

# @OpService ops
# @Dataset input
# @Dataset kernel
# @OUTPUT ImgPlus out

out = ops.run("filter.convolve", input, kernel)
Note: the types we copied and pasted just represent a minimum requirement. Open images will almost always be Datasets, which themselves have an ImgPlus, which has an Img which is a RandomAccessibleInterval. If you want multiple input images you should use Dataset. A safe alternative for single inputs is ImgPlus. Both of these classes contain additional metadata which can be useful in your script.

6. Our script is done! If we open a base image and kernel in ImageJ we can run our script. The OpService is populated automatically by the ImageJ framework, and an input window is automatically created to select the images:

border"1200px

Running Ops

Although you can run selected Ops through the Op Finder, this method lacks reproducibility and should not be used as a substitute for a proper script or plugin when using Ops in a scientific workflow. This functionality is intended to allow a rapid preview of what effect an Op will have on a dataset.

The play button essentially automates the process of turning an Op into a script: optional parameters are discarded and required parameters are annotated. Because of this, Ops with arcane or unusual parameters may fail to run because the framework does not know how to provide them.

Thus it is recommended to run Ops primarily from the User view, as these Ops focus on images and numbers, which can automatically be provided by the framework (via open images and input panels, respectively).