A job (an instance of a software) can be run through the command-line or through the "Run Job" dialog in the "Jobs" Panel where parameter values have to be filled.
In some applications, end-users want to apply an algorithm on a specific region of interest of their image, without switching back and forth between the Explore and the Job panels, and maybe without the need to understand parameters and their values.
Here we present the concept of Job template to allow the execution of a software on a specific annotation with pre-filled parameters and direcly in the "Explore" view of an image.
Job template presentation
The “job template” allow to launch a software with pre-filled parameters on a determined region (annotation) of an image.
After defining a “job template”, a user can easily launch a software on a specific region of interest (see image bellow):
- the user select an annotation (or draw a ROI annotation),
- the user choose the “job template” (a software with pre-filled parameters) to user,
- the user click on “Launch” button
Everything is done on the image explore view and each user can easily use its software (pre-filled parameters may be define by another user).
How to define job template
The first condition is to have a software already defined in the current project.
The software must have at least a parameter name “annotation”. This parameter will be automatically filled (with the identifier of the annotation) when you will launch the job from the explore view.
- A software s in the project p,
- A parameter “annotation” (type: Number) for the software s.
You need to follow these steps to create a full “job template” shortcut:
- create a new “job template” for a software in a project,
- add “job parameter” parameters (pre-filled parameters) for each parameters not set by the server. A “job template” is a “job” with pre-filled parameters, so we can link a “job template” to a “job parameter”.
Example in Java
Imagine a simple software “ComputeAnnotationStat” computing annotations area with term T inside an annotation (ROI).
This software has 4 steps:
- Get the annotation ROI from Cytomine (the location properties is needed),
- Search on Cytomine all annotations with the term T inside the ROI location,
- Compute the sum of the area for all annotations,
- Add a property to the annotation ROI. The key is "AREA_OF_TERM" (where TERM is the term T name) and the value is the areas sum.
You have 2 parameters not set by the server:
- annotation id,
- term id.
We can create a “job template” to easily compute annotation stats with the term “tumor” inisde the ROI annotation. The annotation (ROI) will be automatically set by the “job template” mechanism. The term will be pre-filled.
We suppose that the software “ComputeAnnotationStat” is in the current project “Test”. We will create a “job template” ComputeTumorStat.
The “job template” has a pre-filled parameter “tumor” (id) for the parameter “term”. In the explore view from the cytomine web client, you will see a new “job template” choice: “ ComputeTumorStat”.
Example in Python
As previously explained, in addition to other parameters, your software should have an "annotation" parameter:
You can create your jobTemplate using add_job_template function and add_job_parameters (with the job_template.id):
When you execute the jobTemplate "CountObjects" through the Cytomine-WebUI JobTemplate panel (in the Explore view), Cytomine-Core will automatically add the "annotation" parameter value to the execution command of your software
so that your software knows where in the image it has to work.
In the screenshot below, you can see the JobTemplate panel (where there is a software named "includedcount7" with several jobtemplates named "countmitoticcells..."). This software perform counting of a certain type of cells (i.e. with
a specific ontology term, here depicted in green), and create an annotation property (included_count) that encode the number of these cells that is displayed in the middle of the rectangular region of interest. The JobTemplate actually
contains the pre-filled parameter value that encodes the ontology term that corresponds to the cell type of interest.
Of course it is possible to design more complex workflows e.g. where a jobTemplate corresponds to a cell detection algorithm (with pre-filled parameter values corresponding to processing steps) followed by cell counting in order to
allow the end-user to apply complex algorithms directly within the image.