Building a Plug-in
This page explains how to build your CIRCUS CS Plug-in. We assume the basic understanding of Docker.
1. Build Your Main Executable#
As described in the previous page, a program written in any language can work as a CIRCUS plug-in. Ensure the following:
- Your executable (and sub-processes) does not have network access. Your image must be self-contained.
- Your executable must be able to read input data from
/circus/in/and output results to/circus/out/. - Your executable must end with a status code of
0if it has finished processing successfully. - (Optional) Your executable can print log text into the standard output (stdout), which will help troubleshooting when something went wrong.
2. Write the plugin.json Manifest File#
Create a JSON file called plugin.json. This is a manifest file that contains the plug-in name, version, author, etc.
{
"type": "CAD",
"pluginName": "My-Detector",
"version": "1.0.0",
"description": "Detects something",
"icon": {
"glyph": "calc",
"color": "#ffffff",
"backgroundColor": "#000000"
},
"displayStrategy": [
{
"caption": "Results",
"type": "VolumeOverlay"
},
{
"feedbackKey": "evaluation",
"caption": "Score",
"type": "Numeric",
"options": {
"minimum": 1,
"maximum": 5,
"multipleOf": 1
}
}
]
}Note that you cannot write comments in the real JSON file.
type- This must be the string literal "CAD".
pluginName- The name of this plug-in. It is not used internally to distinguish plugins, but please choose one that is as unique as possible.
version- The version of this plug-in. Must be semver-compatible.
icon- The icon of this plug-in.
icon.glyph- The icon of this plug-in. See
packages/circus-iconsfor available glyphs. icon.color- Color of the icon. Must be in the 6-digit hex format (e.g.,
#ffff00). icon.backgroundColor- Background color of the icon. Must be in the 6-digit hex format.
displayStrategy- An array of objects that describes how to display the plug-in results by default. For details of how this works, read Presenting CAD Results. If you want examples, refer to Built-in Displays reference pages.
3. Write the Dockerfile#
There is little that's special here, but make sure the following:
plugin.jsonis located at the root directory (/plugin.json).- There is a
CMDline that locates to your main executable along with the desired arguments. A minimum Dockerfile will look like this:
FROM ubuntu:20.04
COPY ./my-cad
CMD /my-cad --input=/circus/in --output=/circus/out4. Build the Image#
$ docker build5. Test Your Plug-in#
-
Make a directory similar to this:
📂test-dir/ 📂in/ 0.raw 0.mhd 0.json 📂out/The contents of the
infile can be downloaded via CIRCUS web UI (You need adownloadVolumeglobal privilege). -
Run the following.
$ docker run --rm my-cad:1.0.0 -v /test-dir:/circusThe
--rmoption auto-deletes the container after the container's main process has finished. -
Investigate the
test-dir/outdirectory and seeresults.jsonand other output files are correctly generated.
6. Pack and Distribute#
To pack your docker image into a gar.gz archive, do:
$ docker save my-detector | gzip > my-detector-1.0.0.tar.gzThen this archive can be loaded into another machine like so (*.gz files are automatically unzpped):
$ cat my-detector-1.0.0.tar.gz | docker loadAlternatively, your image can be hosted in Docker Hub or any other container registries.
7. Install the plug-in#
Refer to the admin page: Registration of CS Plug-ins